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

Paramètres de requête

Paramètre	Type	Obligatoire	Description
`model`	string	✅	Slug du modèle, par ex. `bytedance/seedance-2.5` 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
`real_person`	boolean	—	`false` par défaut. Utilisez `true` pour prétraiter les références de personnes réelles avant la génération ; au moins une référence image est requise
`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	—	`type` épingle le fournisseur, `options` transmet les paramètres propres au fournisseur. Voir Routage des fournisseurs

É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.

`real_person` : Images de référence de personnes réelles

Consultez Images de référence de personnes réelles pour le parcours Ofox en une étape, la comparaison avec l’enrôlement Seedance et les conseils de nouvel essai.

Définissez le champ de premier niveau real_person sur true lorsqu’une image de référence contient une personne réelle identifiable. Ofox applique un prétraitement respectueux de la vie privée à chaque image du champ de référence choisi avant d’envoyer la requête de génération. La valeur par défaut est false, donc les requêtes existantes ne changent pas.


{
  "model": "bytedance/seedance-2.0",
  "prompt": "La personne traverse un marché nocturne cinématographique",
  "real_person": true,
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/person.jpg" }
    }
  ]
}

Vous pouvez utiliser real_person avec des images dans frame_images ou input_references ; ces deux champs restent mutuellement exclusifs. Au moins une référence image est requise, sinon l’API renvoie 400 invalid_request.

Le prétraitement peut réduire les faux rejets des contrôles anti-deepfake du fournisseur en amont, mais il ne contourne pas sa politique de contenu et ne garantit pas l’acceptation. Le fournisseur peut encore rejeter la requête ; une tâche rejetée n’est pas facturée. Corrigez l’entrée ou réessayez. Consultez les erreurs de prétraitement real_person.

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


# Optionnel : épingler un fournisseur. Sans ce champ, la plateforme route pour vous
# "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
  }'

Image vers vidéo

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

Terminal


# Optionnel : épingler un fournisseur. Sans ce champ, la plateforme route pour vous
# "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.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


# Optionnel : épingler un fournisseur. Sans ce champ, la plateforme route pour vous
# "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.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


# Optionnel : épingler un fournisseur. Sans ce champ, la plateforme route pour vous
# "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.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


# Optionnel : épingler un fournisseur. Sans ce champ, la plateforme route pour vous
# "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.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": "bytedance/seedance-2.5",
  "prompt": "...",
  "callback_url": "https://your-app.example/webhooks/ofox-video"
}

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

Épingler un fournisseur (provider.type)

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": "bytedance/seedance-2.5",
  "prompt": "...",
  "size": "1280x720"
}

Audio + seed

Utilisez le champ racine provider.type pour épingler la tâche à un fournisseur — voir Routage des fournisseurs.

Créer une vidéo

Paramètres de requête

Élément frame_images[]

Élément input_references[]

real_person : Images de référence de personnes réelles

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)

Épingler un fournisseur (provider.type)

Taille exacte en pixels

Audio + seed

Élément `frame_images[]`

Élément `input_references[]`

`real_person` : Images de référence de personnes réelles