Crear video

Envía una tarea de generación de video. La solicitud devuelve 202 Accepted inmediatamente con un id de tarea y una URL de consulta: la generación se ejecuta de forma asíncrona. Consulta la tarea o recibe un webhook, luego lee el resultado con Obtener estado del video.


POST https://api.ofox.ai/v1/videos

Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Descripción
`model`	string	✅	Slug del modelo, por ejemplo `google/veo-3.1` o `bytedance/seedance-2.0`
`prompt`	string	✅	Descripción textual del video
`duration`	integer	—	Duración del video en segundos
`resolution`	string	—	`480p` / `720p` / `1080p` / `1K` / `2K` / `4K`
`aspect_ratio`	string	—	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `3:2` / `2:3` / `21:9` / `9:21`
`size`	string	—	Pixeles exactos `WIDTHxHEIGHT` (por ejemplo `1280x720`), alternativa a `resolution` + `aspect_ratio`
`frame_images`	array	—	Control de fotogramas (imagen a video / primer y último fotograma). Presente ⇒ se trata como imagen a video. Ver abajo
`input_references`	array	—	Guía de sujeto / estilo (referencia a video), no anclas precisas de fotograma. Ver abajo
`generate_audio`	boolean	—	Valor predeterminado `true` en modelos que admiten salida de audio
`seed`	integer	—	Semilla de generación determinística (no garantizada en todos los proveedores)
`callback_url`	string	—	URL de webhook para estado terminal; debe usar HTTPS (ver Webhooks)
`provider`	object	—	Passthrough específico del proveedor, ver Provider passthrough

Elemento de `frame_images[]`

Cada elemento fija un fotograma de la salida. frame_type es first_frame o last_frame.


{
  "type": "image_url",
  "image_url": { "url": "https://example.com/first.jpg" },
  "frame_type": "first_frame"
}

Elemento de `input_references[]`

Pasa referencias de imagen / audio / video por type: guían el sujeto, el estilo y la consistencia, no anclas precisas de fotograma:


{ "type": "image_url", "image_url": { "url": "https://example.com/subject.jpg" } }
{ "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } }
{ "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" } }

Medio	`type`	Cantidad máxima	Otras restricciones
Imagen	`image_url`	≤ 9	—
Audio	`audio_url`	≤ 3	≤ 15s por clip
Video	`video_url`	≤ 1	—

Superar cualquier límite devuelve 400 too_many_references (ver Errores).

frame_images e input_references son mutuamente excluyentes: una solicitud usa uno u otro, nunca ambos. Enviar ambos devuelve 400 references_conflict.

Modo de generación (implícito)

No existe un campo gen_mode. El modo se infiere a partir de los inputs que envías:

Modo	Detectado cuando
`text2video`	Ni `frame_images` ni `input_references`
`img2video`	`frame_images` con un `first_frame`
`img2video_end`	`frame_images` con `first_frame` + `last_frame`
`imgref2video`	`input_references`, solo imágenes
`mixref2video`	`input_references` mezclando imagen / audio / video

Respuesta

202 Accepted: la tarea se acepta con status: "pending" y un polling_url:


{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "pending",
  "polling_url": "https://api.ofox.ai/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718"
}

Consulta polling_url (o espera un webhook) hasta que la tarea llegue a un estado terminal; ver Obtener estado del video.

Ejemplos de solicitud

Un solo esquema de /v1/videos cubre todos los modos de generación; el modo se elige implícitamente a partir de tus inputs. Cada ejemplo de abajo funciona tal cual.

Texto a video

Sin frame_images / input_references → texto a video.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

Imagen a video

frame_images con un first_frame → anima desde una imagen inicial.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Make the dog in the frame start running",
    "duration": 5,
    "frame_images": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/dog.jpg" },
        "frame_type": "first_frame"
      }
    ]
  }'

Primer y último fotograma

frame_images con first_frame + last_frame → interpola entre dos fotogramas.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Smoothly transition between the two frames",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/start.jpg" }, "frame_type": "first_frame" },
      { "type": "image_url", "image_url": { "url": "https://example.com/end.jpg" },   "frame_type": "last_frame" }
    ]
  }'

Referencia de imagen

input_references solo con imágenes (guía sujeto / estilo, no anclas de fotograma): hasta 9.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "This character skiing down a snowy mountain",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/character.jpg" } },
      { "type": "image_url", "image_url": { "url": "https://example.com/style-ref.jpg" } }
    ]
  }'

Referencia mixta

input_references mezclando imagen / audio / video (imagen ≤ 9 · audio ≤ 3, ≤ 15s cada uno · video ≤ 1).

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Have the character speak in the tone of this voice clip, in the style of this reference video",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/character.jpg" } },
      { "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } },
      { "type": "video_url", "video_url": { "url": "https://example.com/style-ref.mp4" } }
    ]
  }'

Opciones combinables

Los campos de abajo son ortogonales al modo de generación: agrega cualquiera de ellos a cualquier cuerpo de solicitud anterior.

Webhook (callback_url)

Recibe un POST en tu endpoint cuando la tarea llegue a un estado terminal, en lugar de consultar.


{
  "model": "google/veo-3.1",
  "prompt": "...",
  "callback_url": "https://your-app.example/webhooks/ofox-video"
}

callback_url debe usar HTTPS. Consulta Webhooks para ver el payload y la firma.

Provider passthrough

Pasa parámetros específicos del proveedor (por ejemplo watermark) mediante provider.options.<slug>.


{
  "model": "alibaba/wan-2.7",
  "prompt": "...",
  "provider": {
    "options": { "dashscope": { "watermark": false } }
  }
}

Tamaño exacto en pixeles

Usa size para pixeles exactos en lugar de resolution + aspect_ratio.


{
  "model": "google/veo-3.1",
  "prompt": "...",
  "size": "1280x720"
}

Audio + seed

Habilita la salida de audio y fija una semilla determinística.


{
  "model": "google/veo-3.1",
  "prompt": "...",
  "generate_audio": true,
  "seed": 42
}

Provider passthrough

Los parámetros específicos del proveedor pasan por provider.options.<slug>: solo el proveedor correspondiente los recibe. Parámetros como watermark no son compatibles con todos los modelos, por lo que viven en el passthrough del proveedor en lugar de ser campos de primer nivel (esto sigue la convención de provider-passthrough de OpenRouter). Las opciones de passthrough que acepta un modelo dependen de sus capacidades.


{
  "model": "alibaba/wan-2.7",
  "prompt": "...",
  "provider": {
    "options": {
      "dashscope": { "watermark": false, "audio_setting": "..." }
    }
  }
}

Crear video

Parámetros de solicitud

Elemento de frame_images[]

Elemento de input_references[]

Modo de generación (implícito)

Respuesta

Ejemplos de solicitud

Texto a video

Imagen a video

Primer y último fotograma

Referencia de imagen

Referencia mixta

Opciones combinables

Webhook (callback_url)

Provider passthrough

Tamaño exacto en pixeles

Audio + seed

Provider passthrough

Elemento de `frame_images[]`

Elemento de `input_references[]`