Créer une vidéo

Soumettez une tâche de génération vidéo. La requête renvoie immédiatement 202 Accepted avec un id de tâche et une URL de polling — la génération s’exécute de façon asynchrone. Interrogez la tâche ou recevez un webhook, puis lisez le résultat avec Obtenir le statut vidéo.


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

Paramètres de requête

Paramètre	Type	Obligatoire	Description
`model`	string	✅	Slug du modèle, par ex. `google/veo-3.1` ou `bytedance/seedance-2.0`
`prompt`	string	✅	Description textuelle de la vidéo
`duration`	integer	—	Durée de la vidéo en secondes
`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	—	Pixels exacts `WIDTHxHEIGHT` (par ex. `1280x720`), une alternative à `resolution` + `aspect_ratio`
`frame_images`	array	—	Contrôle des images (image-vers-vidéo / première et dernière image). Présent ⇒ traité comme image-vers-vidéo. Voir ci-dessous
`input_references`	array	—	Guide le sujet / style (référence-vers-vidéo), sans ancrages précis d’image. Voir ci-dessous
`generate_audio`	boolean	—	Par défaut `true` sur les modèles qui prennent en charge la sortie audio
`seed`	integer	—	Graine de génération déterministe (non garantie chez tous les fournisseurs)
`callback_url`	string	—	URL de webhook d’état terminal, doit être en HTTPS (voir Webhooks)
`provider`	object	—	Transmission de paramètres propres au fournisseur, voir Provider passthrough

Élément `frame_images[]`

Chaque élément fixe une image de la sortie. frame_type vaut first_frame ou last_frame.


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

Élément `input_references[]`

Passez des références image / audio / vidéo par type — elles guident le sujet, le style et la cohérence, pas des ancrages précis d’image :


{ "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" } }

Média	`type`	Nombre max	Autres contraintes
Image	`image_url`	≤ 9	—
Audio	`audio_url`	≤ 3	≤ 15s par clip
Vidéo	`video_url`	≤ 1	—

Dépasser une limite renvoie 400 too_many_references (voir Erreurs).

frame_images et input_references sont mutuellement exclusifs — une même requête utilise l’un ou l’autre, jamais les deux. Envoyer les deux renvoie 400 references_conflict.

Mode de génération (implicite)

Il n’y a pas de champ gen_mode. Le mode est déduit des entrées envoyées :

Mode	Détecté quand
`text2video`	Ni `frame_images` ni `input_references`
`img2video`	`frame_images` avec un `first_frame`
`img2video_end`	`frame_images` avec `first_frame` + `last_frame`
`imgref2video`	`input_references`, images uniquement
`mixref2video`	`input_references` mélangeant image / audio / vidéo

Réponse

202 Accepted — la tâche est acceptée avec status: "pending" et un polling_url :


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

Interrogez polling_url (ou attendez un webhook) jusqu’à ce que la tâche atteigne un état terminal — voir Obtenir le statut vidéo.

Exemples de requêtes

Un seul schéma /v1/videos couvre tous les modes de génération ; le mode est choisi implicitement à partir de vos entrées. Chaque exemple ci-dessous fonctionne tel quel.

Texte vers vidéo

Aucun frame_images / input_references → texte-vers-vidéo.

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
  }'

Image vers vidéo

frame_images avec un first_frame → animer à partir d’une image de départ.

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"
      }
    ]
  }'

Première et dernière image

frame_images avec first_frame + last_frame → interpoler entre deux images.

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" }
    ]
  }'

Référence image

input_references avec des images uniquement (guide le sujet / style, pas des ancrages d’image) — jusqu’à 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" } }
    ]
  }'

Référence mixte

input_references mélangeant image / audio / vidéo (image ≤ 9 · audio ≤ 3, ≤ 15s chacun · vidéo ≤ 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" } }
    ]
  }'

Options cumulables

Les champs ci-dessous sont indépendants du mode de génération — ajoutez n’importe lequel à n’importe quel corps de requête ci-dessus.

Webhook (callback_url)

Recevez un POST sur votre endpoint lorsque la tâche atteint un état terminal, au lieu de l’interroger.


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

callback_url doit être en HTTPS. Voir Webhooks pour le payload et la signature.

Provider passthrough

Passez des paramètres propres au fournisseur (par ex. watermark) via provider.options.<slug>.


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

Taille exacte en pixels

Utilisez size pour des pixels exacts à la place de resolution + aspect_ratio.


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

Audio + seed

Activez la sortie audio et fixez une graine déterministe.


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

Provider passthrough

Les paramètres propres au fournisseur passent par provider.options.<slug> — seul le fournisseur correspondant les reçoit. Les paramètres comme watermark ne sont pas pris en charge par tous les modèles ; ils se trouvent donc dans le provider passthrough plutôt que dans des champs de premier niveau (cela suit la convention provider-passthrough d’OpenRouter). Les options passthrough acceptées par un modèle dépendent de ses capacités.


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

Créer une vidéo

Paramètres de requête

Élément frame_images[]

Élément input_references[]

Mode de génération (implicite)

Réponse

Exemples de requêtes

Texte vers vidéo

Image vers vidéo

Première et dernière image

Référence image

Référence mixte

Options cumulables

Webhook (callback_url)

Provider passthrough

Taille exacte en pixels

Audio + seed

Provider passthrough

Élément `frame_images[]`

Élément `input_references[]`