# Crear con la API y el MCP Crea imágenes de producto, video, locuciones, música y anuncios terminados desde tu propio código o desde un agente de IA. Un solo saldo paga el estudio, la API REST y el servidor 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. - URL base: `https://mobyvid.com/api/v1` - Autenticación: `Bearer ` - Formato: `JSON` - OpenAPI: `/api/v1/openapi.json` **Clave de API en menos de un minuto** Regístrate, confirma tu email y abre Claves de API en el estudio para crear una. Se muestra una sola vez, así que cópiala enseguida. Puedes ponerle un límite diario de créditos. [Obtener clave de API](https://mobyvid.com/es/registro?next=/app/api) ## Autenticación Crea una clave en [el estudio](https://mobyvid.com/app/api) 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 `. También vale `X-API-Key: `. Los ejemplos la leen de `STAGLIGHT_API_KEY`. Terminal: ```bash 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](https://mobyvid.com/app/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](https://mobyvid.com/app/creditos). ## 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. | Límite | Se cuenta por | Se aplica a | |---|---|---| | 30 por minuto | Clave de API | Llamadas que crean: `POST /api/v1/characters`, `DELETE /api/v1/characters/{character_id}`, `PATCH /api/v1/characters/{character_id}`, `POST /api/v1/characters/{character_id}/sheet`, `POST /api/v1/formats/{format_id}/series`, `DELETE /api/v1/formats/{format_id}/series/{series_id}`, `PATCH /api/v1/formats/{format_id}/series/{series_id}`, `POST /api/v1/generate/image`, `POST /api/v1/generate/video`, `POST /api/v1/jobs`, `POST /api/v1/products`, `POST /api/v1/runs`, `POST /api/v1/runs/from-analysis`, `POST /api/v1/runs/propose`, `POST /api/v1/runs/{run_id}/approve`, `POST /api/v1/runs/{run_id}/redo`, `POST /api/v1/runs/{run_id}/scenes`, `POST /api/v1/scripts`, `POST /api/v1/scripts/{job_id}/make`, `PUT /api/v1/studio/library`, `POST /api/v1/studio/{studio_id}/helpers/{name}`, `POST /api/v1/studio/{studio_id}/helpers/{name}/cancel`, `POST /api/v1/studio/{studio_id}/runs`, `POST /api/v1/studio/{studio_id}/series`, `DELETE /api/v1/studio/{studio_id}/series/{series_id}`, `PATCH /api/v1/studio/{studio_id}/series/{series_id}`, `DELETE /api/v1/studio/{studio_id}/user-cards/{card_id}`, `POST /api/v1/uploads`, `POST /api/v1/uploads/from-library`, `POST /api/v1/uploads/from-url` | | 120 por minuto | Clave de API | Cualquier otra llamada con clave (41 endpoints) | | 60 por minuto | Dirección IP | Llamadas sin una clave válida | - 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. JSON: ```json { "error": { "code": "insufficient_credits", "message": "This needs 63 credits and the balance is 10. Buy credits to continue.", "needed": 63, "balance": 10 } } ``` | Estado | Código | Qué hacer | |---|---|---| | 400 | invalid_idempotency_key | Usa de 1 a 255 caracteres ASCII visibles, por ejemplo un UUID. | | 401 | unauthorized | Falta la clave, es incorrecta o está revocada. | | 402 | insufficient_credits | Incluye `needed` y `balance`. No se cobró nada. Compra créditos y reintenta. | | 402 | daily_limit_reached | Esta clave llegó a su límite diario. Súbelo en el estudio o espera. | | 403 | csrf_failed | Solo en sesiones del navegador. Las claves de API nunca lo ven. | | 404 | not_found | El id no existe o es de otra cuenta. | | 409 | price_above_max | El precio supera tu `max_credits`. No se cobró nada. | | 409 | idempotency_mismatch | Esta clave se usó con otro cuerpo. Usa una clave nueva. | | 409 | idempotency_in_progress | La primera solicitud con esta clave sigue en curso. Reintenta en un segundo. | | 413 | file_too_large | Imágenes de hasta 20 MB, video y audio de hasta 1024 MB. | | 415 | unsupported_media | Usa JPG, PNG, WEBP, GIF, MP4, MOV, WEBM, MP3, WAV o M4A. | | 422 | invalid_request | Revisa `field` y `message`. | | 422 | content_not_allowed | La solicitud pide contenido que no generamos. Consulta los términos. | | 429 | rate_limited | Espera `retry_after` segundos (también en `Retry-After`). | | 503 | service_unavailable | La generación está en pausa unos minutos. No se cobró nada. | ### 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=`. 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 Terminal: ```bash curl -s -X POST https://mobyvid.com/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) Terminal: ```bash curl -s -X POST https://mobyvid.com/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 Terminal: ```bash curl -s -X POST https://mobyvid.com/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 Terminal: ```bash curl -s "https://mobyvid.com/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). JSON: ```json { "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://mobyvid.com/media/med_19a2b3c4d5e6f7a8b9c0d2/image.png?exp=...&sig=...", "download_url": "https://mobyvid.com/media/med_19a2b3c4d5e6f7a8b9c0d2/image.png?exp=...&sig=...&dl=1" } ], "error": null } ``` ### Descargar el resultado Terminal: ```bash curl -L -o product-ad.png "" ``` 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. Terminal: ```bash curl -s -X POST https://mobyvid.com/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/?wait=30`. Cuando `status` sea `awaiting_approval`, aprueba con `POST /api/v1/runs//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](https://mobyvid.com/es/docs/api): cada endpoint con un ejemplo de curl. - [Configurar el MCP](https://mobyvid.com/es/docs/mcp): Claude Code, Codex y Cursor. - [Kit para agentes](https://mobyvid.com/es/docs/agente): prompt, skill y recetas de FFmpeg. - [Documento OpenAPI](https://mobyvid.com/api/v1/openapi.json) para generadores de código. - [llms.txt](https://mobyvid.com/es/llms.txt) y [llms-full.txt](https://mobyvid.com/es/llms-full.txt) para modelos de lenguaje.