API de solo lectura

Acceso y disponibilidad

Esta guía presenta la versión preliminar de la API de solo lectura. Consulta Claves API en tu cuenta del Studio para comprobar su disponibilidad. Necesitas una suscripción Studio o Scale activa y pagada; un paquete de créditos por sí solo no da acceso.

Las consultas no consumen créditos de generación, aunque tu saldo sea cero. Esta versión no permite subir fotos, iniciar generaciones, descargar archivos, modificar proyectos ni gestionar pagos. Es una API HTTP, no un servidor MCP ni un plugin de ChatGPT.

Crear una clave y conectarte

1. Abre Claves API en tu cuenta del Studio, asigna a la clave el nombre de tu integración y créala. Todas las claves tienen el permiso metadata:read.
2. Copia el secreto cuando aparezca: solo se muestra una vez. Guárdalo en un gestor de secretos del servidor o en una variable de entorno llamada SEGMENTIT_API_KEY.
3. Envía la clave en la cabecera Authorization: Bearer mediante HTTPS. El ejemplo siguiente lee una variable de entorno existente; no la sustituyas por un secreto en código compartido.

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 del lado del servidor

Configura SEGMENTIT_API_KEY en tu servidor y ejecuta este ejemplo con Node.js 22 o posterior. Crea tu clave en Studio → Cuenta → 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);

Endpoints disponibles

La URL base es https://segmentit.com/api/v1. Todas las solicitudes requieren autenticación y solo acceden a los datos del propietario de la clave. Usa los UUID devueltos por la API. Los campos JSON y los valores de estado se mantienen en inglés en todos los idiomas.

Las tareas muestran el último estado guardado: queued, running, succeeded, failed o cancelled. Consultar una tarea no actualiza el proveedor de procesamiento ni inicia trabajo. Actualiza el proyecto en el Studio para obtener su estado de procesamiento más reciente.

Esquema OpenAPI · JSON

Paginación y respuestas

Las listas devuelven data y pagination. El límite predeterminado es 20; admite de 1 a 50 elementos y un offset de 0 a 10000. Usa nextOffset en la siguiente solicitud y detente cuando sea null. Un proyecto o una tarea individual devuelve únicamente un objeto data. Las fechas siguen 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
  }
}

Límites, errores y reintentos

Una cuenta puede tener 3 claves activas. Caducan a los 90 días. Todas comparten un límite de 60 solicitudes por minuto y cuenta. Ante una respuesta 429, espera los segundos indicados en Retry-After antes de reintentar; evita las consultas continuas.

Los permisos se comprueban en cada solicitud. Si tu suscripción deja de cumplir los requisitos, la API devuelve 403 aunque la clave no haya caducado. Puedes seguir revocando claves en el Studio. Una clave revocada o caducada devuelve 401; crea otra cuando tengas acceso.

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

Protege tu integración

Ejecuta las solicitudes en tu servidor o en un script local de confianza. Nunca incluyas claves en una URL, JavaScript del navegador, un repositorio público, capturas o registros. Revoca de inmediato cualquier clave expuesta. Una clave puede leer metadatos de todos tus proyectos, no solo de uno seleccionado.

Las respuestas solo incluyen metadatos: no contienen fotos originales, máscaras, contenido GLB, URL de archivos ni credenciales del proveedor. Sigue usando el Studio para ver y descargar tus creaciones.