Referencia de la API

Resumen

La API pública de CyberBara se expone bajo /api/v1 y permite:

Generar tareas de imagen
Generar tareas de video
Subir imágenes de referencia y obtener URL reutilizables
Consultar el estado de las tareas y sus resultados
Consultar el saldo de créditos
Consultar el uso de créditos
Estimar créditos antes de crear una tarea
Listar modelos públicos

Los detalles del proveedor se ocultan intencionadamente a los clientes.

URL base

Usa tu propio dominio desplegado.

https://<your-domain>

Ejemplo:

https://cyberbara-preview.iamzerolu.workers.dev

Autenticación

Pasa tu API key en una de estas cabeceras:

Authorization: Bearer <API_KEY>

x-api-key: <API_KEY>

Si falta o es inválida, la API devuelve 401.

Formato de respuesta

Éxito:

{
  "data": {}
}

Error:

{
  "error": {
    "code": "error_code",
    "message": "human readable message",
    "details": {}
  }
}

Modelos

`GET /api/v1/models`

Parámetro de consulta opcional:

media_type=image|video

Ejemplo:

curl -X GET 'https://<your-domain>/api/v1/models?media_type=video' \
  -H 'Authorization: Bearer <API_KEY>'

Ejemplo de respuesta:

{
  "data": {
    "models": [
      {
        "model": "sora-2",
        "media_type": "video",
        "supported_scenes": ["text-to-video", "image-to-video"]
      },
      {
        "model": "kling-2.6",
        "media_type": "video",
        "supported_scenes": ["text-to-video", "image-to-video"]
      }
    ],
    "total": 2
  }
}

Ejemplo de error (invalid_media_type):

{
  "error": {
    "code": "invalid_media_type",
    "message": "media_type must be \"image\" or \"video\"."
  }
}

Uploads

`POST /api/v1/uploads/images`

Sube una o varias imágenes de referencia y luego usa las URL devueltas en options.image_input.

Solicitud:

Content-Type: multipart/form-data
nombre del campo: files (o file para una sola subida)
máximo de archivos por solicitud: 10
tamaño máximo por archivo: 10MB
tipos MIME admitidos: image/jpeg, image/jpg, image/png, image/webp, image/gif, image/svg+xml, image/avif, image/heic, image/heif

Ejemplo:

curl -X POST 'https://<your-domain>/api/v1/uploads/images' \
  -H 'Authorization: Bearer <API_KEY>' \
  -F 'files=@./reference.png'

Ejemplo de respuesta:

{
  "data": {
    "files": [
      {
        "url": "https://cdn.example.com/uploads/api/v1/uploads/3e7e48e6/7f2f25f8d6c26f11b2a5bb6b3f7f4a28.png",
        "key": "api/v1/uploads/3e7e48e6/7f2f25f8d6c26f11b2a5bb6b3f7f4a28.png",
        "filename": "reference.png",
        "content_type": "image/png",
        "size": 245123,
        "deduped": false
      }
    ],
    "urls": [
      "https://cdn.example.com/uploads/api/v1/uploads/3e7e48e6/7f2f25f8d6c26f11b2a5bb6b3f7f4a28.png"
    ],
    "count": 1
  }
}

`POST /api/v1/uploads/videos`

Sube un video de referencia y luego usa las URL devueltas en options.video_input (o en options.video_url para seedance-2-watermark-remover).

Solicitud:

Content-Type: multipart/form-data
nombre del campo: files (o file para una sola subida)
máximo de archivos por solicitud: 1
tamaño máximo del archivo: 50MB
tipos MIME admitidos: video/mp4, video/quicktime

Ejemplo:

curl -X POST 'https://<your-domain>/api/v1/uploads/videos' \
  -H 'Authorization: Bearer <API_KEY>' \
  -F 'files=@./reference.mp4'

Ejemplo de respuesta:

{
  "data": {
    "files": [
      {
        "url": "https://cdn.example.com/uploads/api/v1/uploads/3e7e48e6/2d9b18f0b5a0a9b4c65b7f6c3b2f7c32.mp4",
        "key": "api/v1/uploads/3e7e48e6/2d9b18f0b5a0a9b4c65b7f6c3b2f7c32.mp4",
        "filename": "reference.mp4",
        "content_type": "video/mp4",
        "size": 1245123,
        "deduped": false
      }
    ],
    "urls": [
      "https://cdn.example.com/uploads/api/v1/uploads/3e7e48e6/2d9b18f0b5a0a9b4c65b7f6c3b2f7c32.mp4"
    ],
    "count": 1
  }
}

Ejemplo de error (invalid_file_type):

{
  "error": {
    "code": "invalid_file_type",
    "message": "Unsupported image type for file \"sample.pdf\".",
    "details": {
      "index": 0,
      "filename": "sample.pdf"
    }
  }
}

Ejemplo de uso de una URL subida para image-to-image:

{
  "model": "nano-banana-pro",
  "scene": "image-to-image",
  "prompt": "Keep composition, make it cinematic at night",
  "options": {
    "image_input": ["https://cdn.example.com/uploads/api/v1/uploads/...png"]
  }
}

Créditos

`GET /api/v1/credits/balance`

Devuelve el saldo actual de créditos.

curl -X GET 'https://<your-domain>/api/v1/credits/balance' \
  -H 'Authorization: Bearer <API_KEY>'

Ejemplo de respuesta:

{
  "data": {
    "user_id": "3e7e48e6-f2fa-4f66-abf8-db7a40eaf517",
    "remaining_credits": 44,
    "updated_at": "2026-03-03T04:08:19.320Z"
  }
}

Ejemplo de error (invalid_api_key):

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key."
  }
}

`POST /api/v1/credits/quote`

Estima los créditos antes de crear una tarea.

Cuerpo de la solicitud:

model requerido
media_type opcional si el modelo puede inferirlo
scene opcional, pero recomendado
options opcional

curl -X POST 'https://<your-domain>/api/v1/credits/quote' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-pro",
    "media_type": "image",
    "scene": "text-to-image",
    "options": { "resolution": "1k" }
  }'

Ejemplo de respuesta:

{
  "data": {
    "model": "nano-banana-pro",
    "media_type": "image",
    "scene": "text-to-image",
    "estimated_credits": 8,
    "remaining_credits": 44,
    "can_afford": true,
    "pricing_rule": "nano-banana-pro",
    "fallback_pricing": false
  }
}

Ejemplo de error (unsupported_model):

{
  "error": {
    "code": "unsupported_model",
    "message": "Model is not supported."
  }
}

`GET /api/v1/credits/usage`

Parámetros de consulta:

page por defecto 1
limit por defecto 20, máximo 100
from opcional, en formato ISO datetime o YYYY-MM-DD
to opcional, en formato ISO datetime o YYYY-MM-DD
Los valores solo fecha se interpretan en UTC (from -> 00:00:00.000Z, to -> 23:59:59.999Z)

curl -X GET 'https://<your-domain>/api/v1/credits/usage?page=1&limit=20&from=2026-03-01&to=2026-03-03' \
  -H 'Authorization: Bearer <API_KEY>'

Ejemplo de respuesta:

{
  "data": {
    "summary": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "total_pages": 1,
      "total_credits_consumed": 28,
      "from": "2026-03-03T00:00:00.000Z",
      "to": "2026-03-03T23:59:59.999Z"
    },
    "items": [
      {
        "id": "0a961844-e042-4a17-bf23-2a5f2680d375",
        "transaction_no": "79739092304928500",
        "credits_consumed": 20,
        "scene": "text-to-video",
        "description": "generate video",
        "media_type": "video",
        "task_id": "2fa99a50-fb96-407b-a562-82de8265f48e",
        "created_at": "2026-03-03T04:31:55.116Z"
      }
    ]
  }
}

Ejemplo de error (invalid_date):

{
  "error": {
    "code": "invalid_date",
    "message": "Invalid date format. Use ISO datetime or YYYY-MM-DD."
  }
}

Ejemplo de error (invalid_date_range):

{
  "error": {
    "code": "invalid_date_range",
    "message": "The \"from\" date must be earlier than the \"to\" date."
  }
}

Generación de tareas

`POST /api/v1/images/generations`

Cuerpo de la solicitud:

model requerido
prompt requerido para la mayoría de modelos
scene opcional (text-to-image / image-to-image)
options opcional

curl -X POST 'https://<your-domain>/api/v1/images/generations' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "A cinematic portrait under neon rain",
    "scene": "text-to-image",
    "options": { "resolution": "1k" }
  }'

La respuesta incluye tu identificador interno de tarea:

{
  "data": {
    "task_id": "uuid",
    "status": "pending",
    "media_type": "image",
    "model": "nano-banana-pro",
    "scene": "text-to-image",
    "credits": {
      "cost": 8,
      "remaining": 36
    },
    "created_at": "2026-03-03T04:29:12.612Z"
  }
}

Ejemplo de error (insufficient_credits):

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits."
  }
}

`POST /api/v1/videos/generations`

Cuerpo de la solicitud:

model requerido
prompt requerido para la mayoría de modelos de video (incluidos seedance-*, kling-2.6, veo-*)
prompt es opcional para sora-2-pro en la capa de validación de la API, pero sigue siendo recomendable
scene opcional (text-to-video / image-to-video / video-to-video)
options opcional

curl -X POST 'https://<your-domain>/api/v1/videos/generations' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "sora-2",
    "prompt": "A calm drone shot over snowy mountains at sunrise",
    "scene": "text-to-video",
    "options": { "duration": "10", "resolution": "standard" }
  }'

Ejemplo de respuesta:

{
  "data": {
    "task_id": "2fa99a50-fb96-407b-a562-82de8265f48e",
    "status": "pending",
    "media_type": "video",
    "model": "sora-2",
    "scene": "text-to-video",
    "credits": {
      "cost": 20,
      "remaining": 16
    },
    "created_at": "2026-03-03T04:31:55.116Z"
  }
}

Ejemplo de error (insufficient_credits):

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits."
  }
}

Opciones específicas por modelo (matriz completa)

Esta sección enumera todas las opciones de solicitud específicas por modelo que actualmente admite la API pública.

Campos generales de la solicitud:

model requerido
prompt depende del modelo (consulta cada modelo más abajo)
scene opcional, pero muy recomendable
options objeto opcional

Inferencia de escena (cuando se omite scene):

API de imagen:
- options.image_input contiene al menos una URL -> image-to-image
- en caso contrario -> text-to-image
API de video:
- options.video_input contiene al menos una URL -> video-to-video
- si no, pero options.image_input contiene al menos una URL -> image-to-video
- en caso contrario -> text-to-video

Campos de opción compartidos:

Campo	Tipo	Significado
`options.image_input`	`string[]`	URL de imagen de entrada/referencia
`options.video_input`	`string[]`	URL de video de entrada/referencia

Notas:

La API pública solo acepta campos options.*. No envíes claves internas del proveedor como image_url, image_urls, input_images o imageUrls (salvo options.video_url para seedance-2-watermark-remover).
Para todos los modelos de abajo, si tanto prompt como options están vacíos, la API devuelve invalid_request.
Algunos modelos validan las opciones de forma estricta; otros las reenvían al endpoint del modelo con validación mínima o nula.
Las opciones desconocidas se ignoran en los modelos con validación estricta; en los modelos pass-through se reenvían.

Modelos de imagen

`nano-banana-2`

Escenas compatibles: text-to-image, image-to-image. Nivel de validación: claves estrictas + normalización ligera.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	Sí	no vacío	Requerido para ambas escenas
`options.image_input`	`string[]`	Requerido para `image-to-image`	array de URL	Si se proporciona y no está vacío, la escena puede inferirse como `image-to-image`
`options.aspect_ratio`	`string`	No	cualquier string no vacío	Se reenvía tal cual
`options.resolution`	`string`	No	normalizado: `1K` / `2K` / `4K`	Entradas como `1k`, `2k`, `4k` se normalizan; el resto se reenvía
`options.output_format`	`string`	No	normalizado: `jpg` / `png`	`jpeg` se convierte en `jpg`; el resto se reenvía
`options.google_search`	`boolean`	No	sin valor por defecto	Solo compatible con `nano-banana-2`

`nano-banana-pro`

Escenas compatibles: text-to-image, image-to-image. Nivel de validación: claves estrictas + normalización ligera.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	Sí	no vacío	Requerido para ambas escenas
`options.image_input`	`string[]`	Requerido para `image-to-image`	array de URL	Si se proporciona y no está vacío, la escena puede inferirse como `image-to-image`
`options.aspect_ratio`	`string`	No	cualquier string no vacío	Se reenvía tal cual
`options.resolution`	`string`	No	normalizado: `1K` / `2K` / `4K`	Entradas como `1k`, `2k`, `4k` se normalizan; el resto se reenvía
`options.output_format`	`string`	No	normalizado: `jpg` / `png`	`jpeg` se convierte en `jpg`; el resto se reenvía

Salvo kling-video-o1, seedance-2-preview, seedance-2-fast-preview y seedance-2-watermark-remover, los modelos siguientes no admiten video-to-video, por lo que no se debe enviar options.video_input.

`sora-2`

Escenas compatibles: text-to-video, image-to-video. Nivel de validación: estricto.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	Sí	no vacío	Requerido para ambas escenas
`options.image_input`	`string[]`	Requerido para `image-to-video`	array de URL	Se usa como referencia de imagen
`options.aspect_ratio`	`string`	No	`landscape` / `portrait` (por defecto `landscape`)	Validación estricta
`options.duration` / `options.n_frames`	`string` o `number`	No	`10` / `15` (por defecto `10`)	Validación estricta
`options.remove_watermark`	`boolean`	No	por defecto `true`	Validación estricta
`options.upload_method`	`string`	No	`s3` / `oss` (por defecto `s3`)	Validación estricta

`sora-2-pro`

Escenas compatibles: text-to-video, image-to-video. Nivel de validación: estricto.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	No para la validación API	opcional	Recomendado
`options.image_input`	`string[]`	Requerido para `image-to-video`	array de URL	Se usa como referencia de imagen
`options.aspect_ratio`	`string`	No	`landscape` / `portrait` (por defecto `landscape`)	Validación estricta
`options.duration` / `options.n_frames`	`string` o `number`	No	`10` / `15` (por defecto `10`)	Validación estricta
`options.resolution` / `options.size`	`string`	No	`standard` / `high` (por defecto `standard`)	Validación estricta

`seedance-2-preview`

Escenas compatibles: text-to-video, image-to-video, video-to-video. Nivel de validación: estricto.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	Sí	no vacío	Requerido para todas las escenas
`options.image_input`	`string[]`	Requerido para `image-to-video`	array de URL (máx. 9)	Se usa como referencia de imagen en el prompt (`@image1`, `@image2`, ...)
`options.video_input`	`string[]`	Requerido para `video-to-video`	URL única	Modo de edición de video de Seedance 2.0. Exactamente una URL.
`options.duration`	`string` o `number`	No (se ignora para `video-to-video`)	`5` / `10` / `15` (por defecto `5`)	En edición de video, la duración de salida coincide con la del video de entrada
`options.aspect_ratio`	`string`	No	`16:9` / `9:16` / `4:3` / `3:4` (por defecto `16:9`)	Se aplica como best-effort; la relación de aspecto de la imagen puede sobrescribirla
`options.parent_task_id`	`string`	No	id de tarea	Extiende una tarea previa de Seedance 2.0; los campos ausentes pueden heredarse del padre

`seedance-2-fast-preview`

Escenas compatibles: text-to-video, image-to-video, video-to-video. Nivel de validación: estricto.

Los campos son los mismos que en seedance-2-preview.

`seedance-2-watermark-remover`

Escenas compatibles: video-to-video. Nivel de validación: estricto.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	No	opcional	No se usa en el watermark remover
`options.video_input`	`string[]`	Sí	URL única	URL del video a procesar
`options.video_url`	`string`	Sí	URL única	Alternativa a `options.video_input`
`options.duration`	`string` o `number`	No	autodetectado	Pista opcional; si se omite, el procesador detecta la duración automáticamente

`seedance-1-pro`

Escenas compatibles: text-to-video, image-to-video. Nivel de validación: estricto + pass-through parcial para algunas cadenas.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	Sí	no vacío	Requerido para ambas escenas
`options.image_input`	`string[]`	Requerido para `image-to-video`	se usa la primera URL	`image-to-video` requiere al menos una imagen
`options.resolution`	`string`	No	por defecto `720p`	Recomendado: `480p`, `720p`, `1080p`
`options.duration`	`string` o `number`	No	por defecto `5`	Recomendado: `5`, `10`
`options.aspect_ratio`	`string`	No	por defecto `16:9`	Se usa para `text-to-video`; `image-to-video` ignora este campo
`options.camera_fixed`	`boolean`	No	sin valor por defecto	Compatible
`options.seed` / `options.seeds`	`integer`	No	`-1` a `2147483647`	Validación estricta del rango
`options.enable_safety_checker`	`boolean`	No	sin valor por defecto	Compatible

`seedance-1-lite`

Escenas compatibles: text-to-video, image-to-video. Nivel de validación: estricto + pass-through parcial para algunas cadenas.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	Sí	no vacío	Requerido para ambas escenas
`options.image_input`	`string[]`	Requerido para `image-to-video`	se usa la primera URL	Si se proporciona una segunda imagen, se usa automáticamente como `end_image_url`
`options.resolution`	`string`	No	por defecto `720p`	Recomendado: `480p`, `720p`, `1080p`
`options.duration`	`string` o `number`	No	por defecto `5`	Recomendado: `5`, `10`
`options.aspect_ratio`	`string`	No	por defecto `16:9`	Se usa para `text-to-video`; `image-to-video` ignora este campo
`options.camera_fixed`	`boolean`	No	sin valor por defecto	Compatible
`options.seed` / `options.seeds`	`integer`	No	`-1` a `2147483647`	Validación estricta del rango
`options.enable_safety_checker`	`boolean`	No	sin valor por defecto	Compatible solo con `text-to-video`
`options.end_image_url`	`string`	No	URL	Compatible con `image-to-video`

`seedance-1-pro-fast`

Escenas compatibles: image-to-video. Nivel de validación: estricto + pass-through parcial para algunas cadenas.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	Sí	no vacío	Requerido
`options.image_input`	`string[]`	Sí	se usa la primera URL	Requerido
`options.resolution`	`string`	No	por defecto `720p`	Recomendado: `720p`, `1080p`
`options.duration`	`string` o `number`	No	por defecto `5`	Recomendado: `5`, `10`

`kling-2.6`

Escenas compatibles: text-to-video, image-to-video. Nivel de validación: estricto.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	Sí	no vacío	Requerido para ambas escenas
`options.image_input`	`string[]`	Requerido para `image-to-video`	array de URL	`image-to-video` requiere al menos una imagen
`options.duration`	`string` o `number`	No	`5` / `10` (por defecto `5`)	Validación estricta
`options.sound`	`boolean`	No	por defecto `false`	Validación estricta
`options.aspect_ratio`	`string`	No	`1:1` / `16:9` / `9:16` (por defecto `16:9`)	Se usa para `text-to-video`; `image-to-video` ignora este campo

`veo-3.1-fast`

Escenas compatibles: text-to-video, image-to-video. Nivel de validación: estricto.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	Sí	no vacío	Requerido
`options.image_input`	`string[]`	Condicional	array de URL	Depende de las reglas de `generationType` indicadas abajo
`options.generationType`	`string`	No	`TEXT_2_VIDEO` / `FIRST_AND_LAST_FRAMES_2_VIDEO` / `REFERENCE_2_VIDEO`	Si se omite, se infiere automáticamente según la cantidad de `image_input`
`options.aspect_ratio`	`string`	No	`16:9` / `9:16` / `Auto` (por defecto `16:9`)	`landscape` -> `16:9`, `portrait` -> `9:16`; `REFERENCE_2_VIDEO` solo permite `16:9`
`options.seed` / `options.seeds`	`integer`	No	`10000` a `99999`	Validación estricta del rango
`options.enableTranslation`	`boolean`	No	sin valor por defecto	Opcional
`options.watermark`	`string`	No	cualquier string no vacío	Opcional

Reglas:

TEXT_2_VIDEO: image_input debe estar vacío
FIRST_AND_LAST_FRAMES_2_VIDEO: image_input debe contener entre 1 y 2 imágenes
REFERENCE_2_VIDEO: image_input debe contener entre 1 y 3 imágenes

`veo-3.1-quality`

Escenas compatibles: text-to-video, image-to-video. Nivel de validación: estricto.

Los campos son los mismos que en veo-3.1-fast, salvo:

options.generationType=REFERENCE_2_VIDEO no es compatible

`kling-video-o1`

Escenas compatibles: video-to-video. Nivel de validación: pass-through.

Campo	Tipo	Requerido	Permitido / Predeterminado	Notas
`prompt`	`string`	Sí	no vacío	Requerido
`options.video_input`	`string[]`	Recomendado en la práctica	se usa la primera URL	Si se omite `scene`, un `video_input` no vacío ayuda a inferir `video-to-video`
`options.image_input`	`string[]`	No	array de URL	Imágenes de referencia opcionales
`options.*`	`any`	No	definido por el proveedor	Todas las claves extra se reenvían

kling-video-o1 es un modelo pass-through. Además de options.video_input, pueden ser necesarios campos options.* definidos por el proveedor.

Checklist rápida de escena y opciones

Generación de imagen:

text-to-image: normalmente solo prompt
image-to-image: incluye options.image_input

Generación de video:

text-to-video: incluye siempre prompt
image-to-video: incluye options.image_input; para la mayoría de modelos, también prompt
video-to-video: incluye options.video_input; incluye prompt si el modelo seleccionado lo requiere

Si quieres un enrutamiento determinista, pasa scene explícitamente.

Consulta de tareas

`GET /api/v1/tasks/{taskId}`

Consulta este endpoint hasta que la tarea alcance un estado final.

curl -X GET 'https://<your-domain>/api/v1/tasks/<TASK_ID>' \
  -H 'Authorization: Bearer <API_KEY>'

Ejemplo de respuesta (pending):

{
  "data": {
    "task": {
      "id": "2fa99a50-fb96-407b-a562-82de8265f48e",
      "status": "pending",
      "media_type": "video",
      "model": "sora-2",
      "scene": "text-to-video",
      "prompt": "A cinematic wide shot of waves hitting black volcanic beach at sunrise",
      "credits": { "cost": 20 },
      "output": { "images": [], "videos": [] },
      "created_at": "2026-03-03T04:31:55.116Z",
      "updated_at": "2026-03-03T04:32:08.511Z"
    }
  }
}

Ejemplo de error (task_not_found):

{
  "error": {
    "code": "task_not_found",
    "message": "Task not found."
  }
}

Valores de estado:

pending
processing
success
failed
canceled

Las respuestas success incluyen las URL de los medios en:

data.task.output.images
data.task.output.videos

Ejemplos de salida de tarea

Éxito de tarea de imagen:

{
  "data": {
    "task": {
      "id": "20b061f3-d051-4795-b355-856325d08f7c",
      "status": "success",
      "media_type": "image",
      "model": "nano-banana-pro",
      "scene": "text-to-image",
      "prompt": "A cinematic portrait under neon rain",
      "credits": { "cost": 8 },
      "output": {
        "images": [
          "https://static.nanobananaproprompts.com/cyberbara_uploads/kie/image/21075dc0-7968-46fd-93fe-e366f558325b.png"
        ],
        "videos": []
      },
      "created_at": "2026-03-03T04:29:12.612Z",
      "updated_at": "2026-03-03T04:29:31.475Z"
    }
  }
}

Éxito de tarea de video:

{
  "data": {
    "task": {
      "id": "2fa99a50-fb96-407b-a562-82de8265f48e",
      "status": "success",
      "media_type": "video",
      "model": "sora-2",
      "scene": "text-to-video",
      "prompt": "A cinematic wide shot of waves hitting black volcanic beach at sunrise",
      "credits": { "cost": 20 },
      "output": {
        "images": [],
        "videos": [
          "https://static.nanobananaproprompts.com/cyberbara_uploads/kie/video/b55bf86d-e3a3-4b81-ae28-a1cff40a71db.mp4"
        ]
      },
      "created_at": "2026-03-03T04:31:55.116Z",
      "updated_at": "2026-03-03T04:34:22.836Z"
    }
  }
}

Tarea fallida:

{
  "data": {
    "task": {
      "id": "341ab8cd-1296-4a5d-968a-cccf60c9caab",
      "status": "failed",
      "media_type": "video",
      "model": "sora-2",
      "scene": "text-to-video",
      "prompt": "A calm drone shot over snowy mountains at sunrise",
      "credits": { "cost": 20 },
      "output": {
        "images": [],
        "videos": []
      },
      "created_at": "2026-03-03T04:30:18.041Z",
      "updated_at": "2026-03-03T04:31:01.420Z"
    }
  }
}

Flujo recomendado

Llama a GET /api/v1/models
Si hace falta, llama a POST /api/v1/uploads/images para obtener URL de referencia
Llama a POST /api/v1/credits/quote
Crea una tarea a través del endpoint de generación de imagen o video
Consulta GET /api/v1/tasks/{taskId} hasta llegar al estado final
Revisa el impacto en facturación con GET /api/v1/credits/usage

Códigos de error comunes (lista no exhaustiva)

api_key_required
invalid_api_key
too_many_requests
invalid_json
invalid_multipart
invalid_date
invalid_date_range
files_required
too_many_files
invalid_file_type
invalid_file_size
file_too_large
invalid_model
unsupported_model
invalid_model_for_media_type
invalid_scene
scene_not_supported
invalid_media_type
invalid_request
service_unavailable
insufficient_credits
upload_failed
generation_failed
invalid_task_id
task_not_found
task_not_ready
query_failed
internal_error

Referencia de la API

En esta página