Skip to Content
Referencia de la APIGeneración de videoCrear video

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.io/v1/videos

Parámetros de solicitud

ParámetroTipoObligatorioDescripción
modelstring✅Slug del modelo, por ejemplo bytedance/seedance-2.5 o bytedance/seedance-2.0
promptstring✅Descripción textual del video
durationinteger—Duración del video en segundos
resolutionstring—480p / 720p / 1080p / 1K / 2K / 4K
aspect_ratiostring—16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 9:21
sizestring—Pixeles exactos WIDTHxHEIGHT (por ejemplo 1280x720), alternativa a resolution + aspect_ratio
frame_imagesarray—Control de fotogramas (imagen a video / primer y último fotograma). Presente ⇒ se trata como imagen a video. Ver abajo
input_referencesarray—Guía de sujeto / estilo (referencia a video), no anclas precisas de fotograma. Ver abajo
real_personboolean—Predeterminado false. Usa true para preprocesar referencias de personas reales antes de generar; requiere al menos una referencia de imagen
generate_audioboolean—Valor predeterminado true en modelos que admiten salida de audio
seedinteger—Semilla de generación determinística (no garantizada en todos los proveedores)
callback_urlstring—URL de webhook para estado terminal; debe usar HTTPS (ver Webhooks)
providerobject—type fija el proveedor, options transmite parámetros propios del proveedor. Ver Enrutamiento de proveedores

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" } }
MediotypeCantidad máximaOtras restricciones
Imagenimage_url≤ 9—
Audioaudio_url≤ 3≤ 15s por clip
Videovideo_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.

real_person: Imágenes de referencia de personas reales

Consulta Imágenes de referencia de personas reales para ver el flujo de un solo paso de Ofox, la comparación con el registro de activos de Seedance y consejos prácticos para reintentar.

Establece el campo de nivel superior real_person en true cuando una imagen de referencia contenga una persona real identificable. Ofox aplica un preprocesamiento que protege la privacidad a cada imagen del campo de referencia elegido antes de enviar la solicitud de generación. El valor predeterminado es false, por lo que las solicitudes existentes no cambian.

{
  "model": "bytedance/seedance-2.0",
  "prompt": "La persona camina por un mercado nocturno cinematográfico",
  "real_person": true,
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/person.jpg" }
    }
  ]
}

Puedes usar real_person con imágenes en frame_images o input_references; ambos campos siguen siendo mutuamente excluyentes. Se requiere al menos una referencia de imagen; de lo contrario, la API devuelve 400 invalid_request.

El preprocesamiento puede reducir falsos rechazos de las comprobaciones anti-deepfake del proveedor upstream, pero no omite su política de contenido ni garantiza la aceptación. El proveedor todavía puede rechazar la solicitud; un trabajo rechazado no se cobra. Corrige la entrada o vuelve a intentarlo. Consulta errores de preprocesamiento de real_person.

Modo de generación (implícito)

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

ModoDetectado cuando
text2videoNi frame_images ni input_references
img2videoframe_images con un first_frame
img2video_endframe_images con first_frame + last_frame
imgref2videoinput_references, solo imágenes
mixref2videoinput_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.io/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.

Sin frame_images / input_references → texto a video.

Terminal
# Opcional: fijar un proveedor. Si lo omites, la plataforma enruta por ti
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.5",
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

Opciones combinables

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

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

{
  "model": "bytedance/seedance-2.5",
  "prompt": "...",
  "callback_url": "https://your-app.example/webhooks/ofox-video"
}

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

Last updated on
Modelos de videoPersonas reales