API en lecture seule

Accès et disponibilité

Ce guide présente l’API en lecture seule, en bêta. Consultez les clés API dans votre compte Studio pour connaître sa disponibilité. Un abonnement Studio ou Scale payé et actif est requis ; un pack de crédits seul ne suffit pas.

Les lectures API ne consomment pas de crédits de génération, même si votre solde est nul. Cette version ne permet ni l’import de photos, ni la génération, ni le téléchargement de fichiers, ni la modification de projets ou de facturation. Il s’agit d’une API HTTP, pas d’un serveur MCP ou d’un plugin ChatGPT.

Créer une clé et se connecter

1. Ouvrez les clés API dans votre compte Studio, donnez à la clé le nom de votre intégration et créez-la. Chaque clé dispose du scope metadata:read.
2. Copiez le secret lorsqu’il apparaît : il n’est affiché qu’une seule fois. Stockez-le dans un gestionnaire de secrets côté serveur ou dans une variable d’environnement nommée SEGMENTIT_API_KEY.
3. Envoyez la clé dans l’en-tête Authorization: Bearer, via HTTPS. L’exemple ci-dessous lit une variable d’environnement existante ; ne la remplacez pas par un secret dans du code partagé.

cURL · Bash

curl --fail-with-body --get \
  'https://segmentit.com/api/v1/projects' \
  --data-urlencode 'limit=20' \
  --header \
  "Authorization: Bearer $SEGMENTIT_API_KEY"

Node.js · JavaScript côté serveur

Définissez SEGMENTIT_API_KEY sur votre serveur, puis exécutez cet exemple avec Node.js 22 ou une version ultérieure. Créez votre clé dans Studio → Compte → API.

const apiKey = process.env.SEGMENTIT_API_KEY;
if (!apiKey) throw new Error('Set SEGMENTIT_API_KEY');

const response = await fetch(
  'https://segmentit.com/api/v1/projects?limit=20',
  {
    headers: { Authorization: `Bearer ${apiKey}` },
    redirect: 'error',
    signal: AbortSignal.timeout(10_000),
  },
);

if (!response.ok) {
  const retryAfter = response.headers.get('Retry-After');
  throw new Error(
    `API error: ${response.status}` +
    (retryAfter ? `; retry after ${retryAfter}s` : ''),
  );
}

const { data: projects, pagination } = await response.json();
console.log(projects);
console.log('Next offset:', pagination.nextOffset);

Points d’accès disponibles

L’URL de base est https://segmentit.com/api/v1. Chaque requête est authentifiée et limitée aux données du propriétaire de la clé. Les identifiants sont les UUID renvoyés par l’API. Les champs JSON et les valeurs de statut restent en anglais dans toutes les langues.

Les tâches indiquent le dernier état enregistré : queued, running, succeeded, failed ou cancelled. Lire une tâche ne consulte pas le fournisseur de calcul et ne déclenche aucun traitement. Actualisez le projet dans le Studio pour obtenir son état de traitement le plus récent.

Schéma OpenAPI · JSON

Pagination et réponses

Les listes renvoient data et pagination. La limite par défaut est de 20 ; choisissez de 1 à 50 éléments et un offset de 0 à 10000. Utilisez nextOffset pour la requête suivante, puis arrêtez-vous lorsqu’il vaut null. Un projet ou une tâche seul renvoie uniquement un objet data. Les dates suivent ISO 8601.

{
  "data": [
    {
      "id": "7b5e26c3-e260-409a-bbb9-b5719f9dbfb0",
      "name": "Launch",
      "kind": "personal",
      "latestJobId": null,
      "createdAt": "2026-10-09T10:00:00.000Z",
      "updatedAt": "2026-10-09T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "nextOffset": null
  }
}

Limites, erreurs et nouvelles tentatives

Un compte peut avoir 3 clés actives. Les clés expirent après 90 jours. Toutes les clés partagent une limite de 60 requêtes par minute et par compte. En cas de réponse 429, attendez le nombre de secondes indiqué dans Retry-After avant de réessayer ; évitez les requêtes en continu.

Les droits sont vérifiés à chaque requête. Lorsque votre abonnement n’est plus éligible, l’API renvoie 403 même si la clé n’a pas expiré. Vous pouvez toujours révoquer vos clés dans le Studio. Une clé révoquée ou expirée renvoie 401 ; créez-en une nouvelle lorsque l’accès est disponible.

{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid API key is required."
  }
}

Protéger votre intégration

Exécutez les requêtes sur votre serveur ou dans un script local de confiance. Ne placez jamais de clé dans une URL, du JavaScript navigateur, un dépôt public, des captures ou des journaux. Révoquez immédiatement toute clé exposée. Une clé peut lire les métadonnées de tous vos projets, pas seulement d’un projet sélectionné.

Les réponses contiennent uniquement des métadonnées : aucune photo source, aucun masque, contenu GLB, lien de fichier ou identifiant du fournisseur. Continuez à utiliser le Studio pour visualiser et télécharger vos créations.