Crear con la API y el MCP

Introducción

Todo lo que haces en el estudio lo puedes hacer desde código: imágenes de producto, clips de video, locuciones, música y anuncios completos con pasos de revisión. Antes de cada trabajo puedes consultar el precio gratis, y si falla, te devolvemos los créditos automáticamente.

Las solicitudes y respuestas son JSON, salvo las subidas, que van como multipart form data. Todas las rutas empiezan con /api/v1, la versión actual.

Autenticación

Crea una clave en el estudio y ponle un límite diario de créditos. La clave se muestra una sola vez. Empieza por sl_live_.

Envíala en cada solicitud como Authorization: Bearer <clave>. También vale X-API-Key: <clave>. Los ejemplos la leen de STAGLIGHT_API_KEY.

export STAGLIGHT_API_KEY="sl_live_..."

Nunca pongas una clave en código del navegador, en un repositorio ni en un chat. Si se filtra, revócala en el estudio.

¿Perdiste tu clave de API?

Las claves se guardan solo como hash, así que nadie puede volver a mostrarte una clave existente, ni siquiera nuestro soporte. Cámbiala tú: inicia sesión, abre Claves de API, crea una clave nueva y revoca la antigua.

Puedes tener hasta 20 claves activas a la vez, así que cambias sin cortes: crea la clave nueva, ponla en tu app y luego revoca la antigua. Una clave revocada deja de funcionar al instante.

Créditos

1 crédito = US$0,01. Cada trabajo tiene su precio antes de empezar, y ese precio se cobra al crearlo.

• Si un trabajo falla, se reembolsa entero y de forma automática.
• Si cancelas un trabajo antes de que empiece, se reembolsa.
• Los créditos comprados no caducan.
• Sin suscripción y sin recargo por usar la API: la API y el MCP tienen los mismos precios que el estudio.
• Al llegar a su límite diario, una clave se detiene con 402 daily_limit_reached.

Consulta el saldo con GET /api/v1/me o, junto con su historial, en GET /api/v1/credits. Compra créditos en el estudio.

Límites de uso

Los límites se cuentan por clave de API en una ventana deslizante de un minuto (por cuenta en las sesiones iniciadas en el navegador). Las llamadas de una misma fila comparten el mismo contador.

• Si pasas el límite, recibes 429 rate_limited con retry_after y un encabezado Retry-After.
• Las consultas largas (wait) mantienen la solicitud abierta hasta 50 s.
• Subidas: imágenes de hasta 20 MB, video y audio de hasta 1024 MB.

El servidor MCP cuenta igual: herramientas de pago 30 por minuto, herramientas gratis 120 por minuto.

Convenciones

Estas reglas se aplican a todos los endpoints.

Errores

Todos los errores tienen la misma forma. code es estable; message es para personas.

{
  "error": {
    "code": "insufficient_credits",
    "message": "This needs 63 credits and the balance is 10. Buy credits to continue.",
    "needed": 63,
    "balance": 10
  }
}

Reintentos e idempotencia

Envía un encabezado Idempotency-Key (un UUID) en cada POST que gaste créditos.

• Misma clave y mismo cuerpo dentro de 24 h: recibes otra vez la primera respuesta, sin cobro nuevo y con el encabezado Idempotent-Replayed: true.
• Misma clave con otro cuerpo: 409 idempotency_mismatch.
• La primera solicitud sigue en curso: 409 idempotency_in_progress. Reintenta en un segundo.
• Una solicitud que terminó en error se olvida, así que puedes reintentarla con la misma clave.

Si se agota el tiempo de espera, no reenvíes a ciegas. Busca antes el trabajo: GET /api/v1/jobs?idempotency_key=<clave>.

Pon un tope de precio con max_credits en el cuerpo. Junto con la clave, un reintento nunca cobra dos veces ni más de lo que permitiste.

Paginación

Las listas aceptan limit (por defecto 20, máximo 100) y responden con next. Pásalo como before para pedir la página siguiente. En la última página next es null.

Listas que se paginan así: GET /api/v1/characters, GET /api/v1/credits, GET /api/v1/jobs, GET /api/v1/media, GET /api/v1/products, GET /api/v1/runs, GET /api/v1/studio/{studio_id}/runs.

Tu primer trabajo

La generación es asíncrona. Estos ejemplos usan curl y leen tu clave de STAGLIGHT_API_KEY.

Subir una foto del producto

curl -s -X POST https://staglight.ai/api/v1/uploads \
  -H "Authorization: Bearer $STAGLIGHT_API_KEY" \
  -F "file=@product.jpg"

La respuesta es un objeto de archivo. Usa su id (med_...) en los parámetros del trabajo. Las imágenes se recodifican, lo que elimina los datos EXIF y GPS. Para subir desde un enlace público, usa POST /api/v1/uploads/from-url.

Consultar el precio (gratis)

curl -s -X POST https://staglight.ai/api/v1/estimate \
  -H "Authorization: Bearer $STAGLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op": "image.nano-banana-pro", "params": {"prompt": "La zapatilla roja sobre fondo de papel blanco, luz suave de mañana", "reference_images": ["med_19a2b3c4d5e6f7a8b9c0d1"], "aspect_ratio": "4:5"}}'

Usa los mismos op y params que en el trabajo. Recibes credits, usd, eta_seconds, tu saldo en balance y enough_credits. No se cobra nada. GET /api/v1/models lista cada op con sus campos.

Crear el trabajo

curl -s -X POST https://staglight.ai/api/v1/jobs \
  -H "Authorization: Bearer $STAGLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"op": "image.nano-banana-pro", "params": {"prompt": "La zapatilla roja sobre fondo de papel blanco, luz suave de mañana", "reference_images": ["med_19a2b3c4d5e6f7a8b9c0d1"], "aspect_ratio": "4:5"}, "max_credits": 40}'

La respuesta es 202 con el trabajo y un encabezado Location. Los créditos se cobran en ese momento. Si el precio supera max_credits, recibes 409 price_above_max y no se cobra nada.

Consultar hasta que termine

curl -s "https://staglight.ai/api/v1/jobs/job_19a2b3c4d5e6f7a8b9c0d1?wait=30" \
  -H "Authorization: Bearer $STAGLIGHT_API_KEY"

wait=30 mantiene la solicitud abierta hasta que el trabajo termina (hasta 50 s). Estados: queued, running, succeeded, failed (reembolsado) y canceled (reembolsado).

{
  "id": "job_19a2b3c4d5e6f7a8b9c0d1",
  "op": "image.nano-banana-pro",
  "status": "succeeded",
  "credits": 23,
  "outputs": [
    {
      "id": "med_19a2b3c4d5e6f7a8b9c0d2",
      "kind": "image",
      "mime": "image/png",
      "width": 1664,
      "height": 2080,
      "url": "https://staglight.ai/media/med_19a2b3c4d5e6f7a8b9c0d2/image.png?exp=...&sig=...",
      "download_url": "https://staglight.ai/media/med_19a2b3c4d5e6f7a8b9c0d2/image.png?exp=...&sig=...&dl=1"
    }
  ],
  "error": null
}

Descargar el resultado

curl -L -o product-ad.png "<outputs[0].download_url>"

Los enlaces van firmados, duran unas 24 h y no necesitan encabezado de autenticación. Vuelve a consultar el trabajo para obtener enlaces nuevos. Los archivos se guardan 30 días.

Anuncios completos (formatos)

Un formato genera un anuncio terminado por pasos: guion, fotogramas clave, clips, voz, música y montaje final. Se detiene en los pasos de revisión para que apruebes una toma o la repitas. GET /api/v1/formats los lista con el precio de cada nivel de calidad.

curl -s -X POST https://staglight.ai/api/v1/runs \
  -H "Authorization: Bearer $STAGLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"format": "product_hero", "product_id": "prd_19a2b3c4d5e6f7a8b9c0d1", "options": {"tier": "draft", "aspect": "9:16", "lang": "es"}}'

Consulta GET /api/v1/runs/<id>?wait=30. Cuando status sea awaiting_approval, aprueba con POST /api/v1/runs/<id>/approve o pide otra toma con /redo. Al empezar solo se cobra el paso de planificación; cada aprobación cobra los pasos que pone en marcha.

Webhooks

Aún no hay webhooks. Consulta con wait=30: responde en cuanto el trabajo termina.

Siguientes pasos

• Referencia de la API: cada endpoint con un ejemplo de curl.
• Configurar el MCP: Claude Code, Codex y Cursor.
• Kit para agentes: prompt, skill y recetas de FFmpeg.
• Documento OpenAPI para generadores de código.
• llms.txt y llms-full.txt para modelos de lenguaje.

Esta página en Markdown · llms.txt