Docs API

Authentification

Base URL : https://api.vivareel.com/api/developer/v1. Tous les endpoints de l'API ouverte utilisent une clé API : Authorization: Bearer sk_live_xxx ou sk_test_xxx.

Réponse et facturation

L'API ouverte renvoie les champs code, message et data ; code 200 = succès. Facturation en points — consultez GET /models pour les tarifs. Interrogez GET /tasks/task_id toutes les 3–5 s pour les tâches asynchrones.

Capacités Wan 3.0

Wan 3.0 est un modèle vidéo de référence tout-en-un. Le même modèle couvre le texte vers vidéo, la première image, la première/dernière image, et les références mixtes image / vidéo / audio. Passez le name renvoyé par GET /models (par exemple wan-3.0). Aucun endpoint dédié n’est nécessaire.

Règles officielles de modes et de combinaisons : Wan3.0 Video Generation API Reference. Cette plateforme les encapsule via POST /api/developer/v1/videos/generations. Les noms de champs diffèrent de input.media[] DashScope ; suivez les paramètres de cette page.

Portée des champs

Commun : model, motion_instruction (obligatoire selon le mode), aspect_ratio, duration_seconds, capability, image_url (selon le mode), last_frame_url (selon le mode ; non pris en charge par HappyHorse), et reference_urls (mode référence).
Multi-modèles : reference_video_urls (Seedance / sémantique Wan3 / Wan2.7 R2V / VivaReel2.0) ; reference_audio_urls (Seedance / sémantique Wan3 / Wan2.7 R2V / minimax-H3).
Sémantique Wan3 : resolution, audio, seed, prompt_extend et smart_duration. Ces champs s’appliquent aux modèles qui utilisent la sémantique Wan 3.
dashscope-wan3.0-video uniquement : watermark, enable_thinking, document_url et web_url.

Modes de génération

Texte vers vidéo : envoyez uniquement motion_instruction, et omettez capability ou passez null.
Première image : envoyez image_url, avec capability first_frame.
Première et dernière images : envoyez image_url et last_frame_url, avec capability flf2v.
Référence multimodale : combinez reference_urls, reference_video_urls et reference_audio_urls. Utilisez capability image_reference. motion_instruction est obligatoire.
Édition / prolongation : envoyez reference_video_urls et décrivez l’intention dans motion_instruction, par exemple « transformer en style argile » ou « prolonger Video 1 vers l’avant ».

Règles d’exclusion

N’envoyez pas image_url / last_frame_url en même temps que reference_urls, reference_video_urls ou reference_audio_urls.
Les modes première image et première/dernière image n’acceptent pas d’audio d’entraînement. Pour un guidage audio, utilisez la référence multimodale (images + audio).
Fournissez motion_instruction, ou un ensemble de médias valide pour le mode choisi.

Limites des médias et de la sortie

Jusqu’à 10 images de référence ; JPEG / JPG / PNG / BMP / WEBP, 240–8000 px par côté, 20 Mo chacune. La limite réelle est max_reference_images.
Jusqu’à 5 clips, 1–15 s chacun, 15 s au total ; mp4 / mov, 100 Mo chacun. La limite réelle est max_reference_videos.
Jusqu’à 5 extraits, 1–15 s chacun, 15 s au total ; wav / mp3, 15 Mo chacun. La limite réelle est max_reference_audios.
Sans vidéo de référence, la durée de sortie est généralement de 2–30 s. Avec une vidéo de référence, durée d’entrée + durée de sortie ≤ 30 s. Vérifiez duration_range / max_duration_seconds.
La sortie est un MP4 à 30 i/s, pouvant inclure dialogues, BGM et effets sonores.

Référencer les médias dans le prompt

Chaque type est numéroté séparément : la 1re image est Image 1, la 1re vidéo est Video 1, le 1er audio est Audio 1. Vous pouvez écrire Image 1, Video 1, ou @Image 1 / @Video 1 / @Audio 1.

Générer une image

POST/api/developer/v1/images/generations

Soumet une tâche de génération d'image autonome (texte vers image ou composition avec images de référence). Renvoie task_id ; interrogez GET /api/developer/v1/tasks/task_id pour le résultat.

Paramètres

name	in	type	required	desc
model	body	string	✓	Nom du modèle image ; listez les modèles via GET /models
prompt	body	string	✓	Description textuelle de l'image à générer
aspect_ratio	body	string	—	Format : 16:9, 9:16, 4:3 ou 3:4
image_resolution	body	string	—	Résolution de sortie : 1K, 2K ou 4K
reference_urls	body	string[]	—	URLs d'images de référence (0–5) ; non vide active le mode composition

Exemple de code

curl -X POST "https://vivareel.ai/api/developer/v1/images/generations" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "dashscope-wan2.1-t2i-turbo",
  "prompt": "一只可爱的猫咪在草地上奔跑",
  "aspect_ratio": "16:9",
  "image_resolution": "2K",
  "reference_urls": [
    "https://example.com/ref1.jpg"
  ]
}'

Exemple de corps de requête

{
  "model": "dashscope-wan2.1-t2i-turbo",
  "prompt": "一只可爱的猫咪在草地上奔跑",
  "aspect_ratio": "16:9",
  "image_resolution": "2K",
  "reference_urls": [
    "https://example.com/ref1.jpg"
  ]
}

Exemple de réponse

{
  "code": 200,
  "message": "ok",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Générer une vidéo

POST/api/developer/v1/videos/generations

Soumet une tâche de génération vidéo autonome. Les modèles tout-en-un comme Wan 3.0 prennent en charge le texte vers vidéo, la première image, la première/dernière image, et les références mixtes image / vidéo / audio. Renvoie task_id ; interrogez GET /api/developer/v1/tasks/task_id pour le résultat.

Paramètres

name	in	type	required	desc
model	body	string	✓	[Commun] Nom du modèle vidéo via GET /models ; généralement wan-3.0 ou dashscope-wan3.0-video
motion_instruction	body	string \| null	—	[Commun / conditionnel] Prompt / instruction de mouvement. Obligatoire pour texte vers vidéo, référence multimodale, édition et prolongation. Vous pouvez citer Image 1 / Video 1 / Audio 1
aspect_ratio	body	16:9 \| 9:16 \| 4:3 \| 3:4 \| null	—	[Commun] Format : 16:9, 9:16, 4:3 ou 3:4
duration_seconds	body	integer \| null	—	[Commun] Durée de sortie en secondes. Voir duration_range / max_duration_seconds via GET /models
capability	body	first_frame \| flf2v \| image_reference \| null	—	[Commun] first_frame, flf2v ou image_reference ; omettre ou null pour déduire (motion_instruction seul = texte vers vidéo)
image_url	body	string \| null	—	[Commun / selon le mode] URL de la première image pour first_frame / flf2v. Ne pas envoyer avec les champs reference_*
last_frame_url	body	string \| null	—	[Commun / selon le mode] URL de la dernière image pour flf2v. Doit être utilisée avec image_url et ne pas être identique. Non pris en charge par HappyHorse
reference_urls	body	string[]	—	[Commun / mode référence] URLs d’images de référence pour image_reference
reference_video_urls	body	string[]	—	[Multi-modèles] Seedance / sémantique Wan3 / Wan2.7 R2V / VivaReel2.0. URLs de vidéos de référence
reference_audio_urls	body	string[]	—	[Multi-modèles] Seedance / sémantique Wan3 / Wan2.7 R2V / minimax-H3. URLs d’audios de référence
resolution	body	480P \| 720P \| 1080P \| null	—	[Sémantique Wan3] Résolution de sortie : 480P, 720P ou 1080P
audio	body	boolean \| null	—	[Sémantique Wan3] Générer ou non l’audio
seed	body	integer \| null	—	[Sémantique Wan3] Graine aléatoire pour reproduire le résultat
watermark	body	boolean \| null	—	[dashscope-wan3.0-video uniquement] Ajouter un filigrane
prompt_extend	body	boolean \| null	—	[Sémantique Wan3] Étendre le prompt
smart_duration	body	boolean	—	[Sémantique Wan3] Durée intelligente ; false par défaut
enable_thinking	body	boolean \| null	—	[dashscope-wan3.0-video uniquement] Activer le raisonnement
document_url	body	string \| null	—	[dashscope-wan3.0-video uniquement] URL de document de référence
web_url	body	string \| null	—	[dashscope-wan3.0-video uniquement] URL de page web de référence

Exemple de code

curl -X POST "https://vivareel.ai/api/developer/v1/videos/generations" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "wan-3.0",
  "motion_instruction": "Video 1 sits on the chair in Image 2 and sings. Image 1 walks over, places Image 3 on the table, and says: the sunshine is so nice today.",
  "aspect_ratio": "9:16",
  "duration_seconds": 8,
  "capability": "image_reference",
  "reference_urls": [
    "https://example.com/character.jpg",
    "https://example.com/chair.jpg",
    "https://example.com/prop.jpg"
  ],
  "reference_video_urls": [
    "https://example.com/performance.mp4"
  ],
  "resolution": "720P",
  "audio": true,
  "prompt_extend": true,
  "smart_duration": false
}'

Exemple de corps de requête

{
  "model": "wan-3.0",
  "motion_instruction": "Video 1 sits on the chair in Image 2 and sings. Image 1 walks over, places Image 3 on the table, and says: the sunshine is so nice today.",
  "aspect_ratio": "9:16",
  "duration_seconds": 8,
  "capability": "image_reference",
  "reference_urls": [
    "https://example.com/character.jpg",
    "https://example.com/chair.jpg",
    "https://example.com/prop.jpg"
  ],
  "reference_video_urls": [
    "https://example.com/performance.mp4"
  ],
  "resolution": "720P",
  "audio": true,
  "prompt_extend": true,
  "smart_duration": false
}

Exemple de réponse

{
  "code": 200,
  "message": "ok",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Remplacer un personnage dans une vidéo

POST/api/developer/v1/videos/replace-character

Soumet une tâche de remplacement de personnage avec 1–3 vidéos sources et 1–9 images de référence. Renvoie task_id ; interrogez GET /api/developer/v1/tasks/task_id pour result_url.

Paramètres

name	in	type	required	desc
video_urls	body	string[]	✓	URLs des vidéos sources (1–3), liens http(s) obligatoires
reference_urls	body	string[]	✓	URLs des images de référence (1–9), liens http(s) obligatoires
prompt	body	string	✓	Prompt de remplacement décrivant l'échange souhaité
resolution	body	string	—	Résolution de sortie ; par défaut 720P
aspect_ratio	body	string	—	Format ; par défaut 9:16
model	body	string	—	Modèle vidéo ; modèle par défaut si omis
duration_seconds	body	number	—	Durée totale des vidéos sources (secondes) pour l'estimation ; détectée automatiquement si omise
seed	body	integer	—	Graine aléatoire pour des résultats reproductibles
watermark	body	boolean	—	Ajouter un filigrane ; par défaut false

Exemple de code

curl -X POST "https://vivareel.ai/api/developer/v1/videos/replace-character" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "video_urls": [
    "https://example.com/video1.mp4"
  ],
  "reference_urls": [
    "https://example.com/face1.jpg",
    "https://example.com/face2.jpg"
  ],
  "prompt": "将视频中的人物替换为参考图中的人物，保持表情和动作自然",
  "resolution": "720P",
  "aspect_ratio": "9:16",
  "model": "dashscope-wan2.1-i2v-plus",
  "duration_seconds": 10.5,
  "seed": 12345,
  "watermark": false
}'

Exemple de corps de requête

{
  "video_urls": [
    "https://example.com/video1.mp4"
  ],
  "reference_urls": [
    "https://example.com/face1.jpg",
    "https://example.com/face2.jpg"
  ],
  "prompt": "将视频中的人物替换为参考图中的人物，保持表情和动作自然",
  "resolution": "720P",
  "aspect_ratio": "9:16",
  "model": "dashscope-wan2.1-i2v-plus",
  "duration_seconds": 10.5,
  "seed": 12345,
  "watermark": false
}

Exemple de réponse

{
  "code": 200,
  "message": "ok",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Statut de la tâche

GET/api/developer/v1/tasks/{task_id}

Interroge l'état et le résultat d'une tâche asynchrone. Interrogez toutes les 3–5 s jusqu'à status completed ou failed.

Paramètres

name	in	type	required	desc
task_id	path	string	✓	ID de tâche renvoyé par les endpoints image/vidéo/remplacement

Exemple de code

curl -X GET "https://vivareel.ai/api/developer/v1/tasks/{task_id}" \
  -H "Authorization: Bearer sk_live_xxx"

Exemple de réponse

{
  "code": 200,
  "message": "ok",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_type": "standalone_image_generate",
    "status": "completed",
    "progress": 1,
    "points_cost": 10,
    "result_url": "https://storage.vivareel.com/output/xxx.png",
    "error_message": null,
    "extra": {
      "model": "dashscope-wan2.1-t2i-turbo",
      "aspect_ratio": "16:9"
    }
  }
}

Téléverser un fichier

POST/api/developer/v1/files

Téléverse un fichier vers le stockage et renvoie une URL utilisable. Pour première image, images, vidéos ou audios de référence (Content-Type: multipart/form-data).

Paramètres

name	in	type	required	desc
file	formData	file	✓	Fichier à téléverser (image, vidéo, audio, etc.)

Exemple de code

curl -X POST "https://vivareel.ai/api/developer/v1/files" \
  -H "Authorization: Bearer sk_live_xxx"

Exemple de réponse

{
  "code": 200,
  "message": "ok",
  "data": {
    "url": "https://storage.vivareel.com/uploads/xxx.jpg",
    "storage_key": "uploads/2024/01/xxx.jpg",
    "original_filename": "my_image.jpg",
    "size_bytes": 204800,
    "content_type": "image/jpeg"
  }
}

Liste des modèles

GET/api/developer/v1/models

Liste les modèles image et vidéo disponibles avec capacités, paramètres pris en charge et tarification. Avant d’appeler Wan 3.0, vérifiez capabilities, duration_range et max_reference_images / videos / audios.

Paramètres

Aucun

Exemple de code

curl -X GET "https://vivareel.ai/api/developer/v1/models" \
  -H "Authorization: Bearer sk_live_xxx"

Exemple de réponse

{
  "code": 200,
  "message": "ok",
  "data": {
    "image_models": [
      {
        "name": "dashscope-wan2.1-t2i-turbo",
        "display_name": "Wan 2.1 Turbo",
        "icon_url": "https://api.vivareel.com/icons/wan.png",
        "capabilities": [
          "text_to_image"
        ],
        "capability_labels": {
          "text_to_image": "文生图"
        },
        "max_reference_images": 0,
        "pricing_by_capability": {
          "text_to_image": {
            "capability": "text_to_image",
            "feature_key": "image_generation",
            "billing_unit": "flat",
            "label": "文生图",
            "points": 10
          }
        }
      }
    ],
    "video_models": [
      {
        "name": "wan-3.0",
        "display_name": "Wan 3.0",
        "icon_url": "https://api.vivareel.com/icons/wan_video.png",
        "capabilities": [
          "text_to_video",
          "first_frame",
          "flf2v",
          "image_reference"
        ],
        "capability_labels": {
          "text_to_video": "文生视频",
          "first_frame": "首帧生视频",
          "flf2v": "首尾帧生视频",
          "image_reference": "全能参考"
        },
        "duration_range": {
          "min": 2,
          "max": 30
        },
        "max_duration_seconds": {
          "text_to_video": 30,
          "first_frame": 30,
          "flf2v": 30,
          "image_reference": 30
        },
        "max_reference_images": 10,
        "max_reference_videos": 5,
        "max_reference_audios": 5,
        "pricing_by_capability": {
          "image_reference": {
            "capability": "image_reference",
            "feature_key": "video_generation_image_reference",
            "billing_unit": "per_second",
            "label": "全能参考",
            "points_per_second": 5
          }
        }
      }
    ]
  }
}

Bibliothèque de portraits virtuels

Ajoutez un portrait https public à la bibliothèque du canal actuel, puis transmettez cette même adresse https pour générer une vidéo. N'envoyez pas asset://.

Avant l'appel

Authentifiez-vous avec une clé API. N'envoyez ni X-Team-Id ni channel. Le canal dépend uniquement du réglage portrait_channel : byteplus pour la bibliothèque officielle, baidu pour Baidu.
L'image doit être une adresse https publique. Pour générer une vidéo, renvoyez cette même adresse. N'utilisez pas asset://.
Ordre d'appel : téléverser le fichier pour obtenir l'adresse, synchroniser, consulter le statut si besoin, générer la vidéo avec la même adresse, puis retirer le portrait lorsqu'il n'est plus utilisé.
message suit Accept-Language. Les exemples ci-dessous sont en chinois.

Erreurs

code	Quand
400	image_url n'est pas une adresse https publique, ou l'image n'est pas dans la bibliothèque du canal actuel.
403	L'utilisateur de la clé API n'est ni VIP ni SVIP.
404	L'image est introuvable lors du retrait.
502	La création ou le retrait côté officiel ou Baidu a échoué. message contient le texte amont.
503	Les identifiants du canal actuel ne sont pas configurés.
504	La synchronisation a expiré.

Changement de canal

Après un basculement côté serveur, de Baidu vers officiel ou l'inverse, rappelez sync pour la même image.

Synchroniser un portrait

POST/api/developer/v1/virtual-assets/sync

Ajoute l'image à la bibliothèque de portraits virtuels du canal actuel. L'appel attend la réussite ou l'échec. Une image déjà Active sur ce canal n'est pas renvoyée. data.outcome vaut created pour un nouvel envoi, already_active si elle est déjà dans la bibliothèque, ou reused si la même image est déjà liée et n'a pas été renvoyée. En cas de succès, in_virtual_asset_library vaut true.

Paramètres

name	in	type	required	desc
image_url	body	string	✓	Adresse https publique de l'image
name	body	string	—	Nom, facultatif

Exemple de code

curl -X POST "https://vivareel.ai/api/developer/v1/virtual-assets/sync" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://cdn.example/a.png",
  "name": "角色甲"
}'

Exemple de corps de requête

{
  "image_url": "https://cdn.example/a.png",
  "name": "角色甲"
}

Exemple de réponse

{
  "code": 200,
  "message": "已加入 Seedance 虚拟资产库",
  "data": {
    "asset_id": 321,
    "image_url": "https://cdn.example/a.png",
    "in_virtual_asset_library": true,
    "outcome": "created"
  },
  "pagination": null
}

Consulter le statut

POST/api/developer/v1/virtual-assets/status

Indique si les adresses sont Active dans la bibliothèque du canal actuel. Un statut Active sur la bibliothèque officielle ne rend pas le résultat true sous le canal Baidu. asset_id vaut null si l'adresse ne correspond à rien.

Paramètres

name	in	type	required	desc
urls	body	string[]	✓	Adresses d'images, de 1 à 200

Exemple de code

curl -X POST "https://vivareel.ai/api/developer/v1/virtual-assets/status" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "urls": [
    "https://cdn.example/a.png"
  ]
}'

Exemple de corps de requête

{
  "urls": [
    "https://cdn.example/a.png"
  ]
}

Exemple de réponse

{
  "code": 200,
  "message": "获取资产 URL 状态成功",
  "data": [
    {
      "url": "https://cdn.example/a.png",
      "in_virtual_asset_library": true,
      "asset_id": 321
    }
  ],
  "pagination": null
}

Retirer un portrait

POST/api/developer/v1/virtual-assets/remove

Ne retire que l'enregistrement du canal actuel. Le canal officiel efface les champs officiels. Le canal Baidu supprime uniquement la liaison Baidu et ne modifie pas les champs officiels. L'enregistrement local de l'image est conservé et peut être synchronisé à nouveau après un retour de canal. in_virtual_asset_library vaut false après le retrait.

Paramètres

name	in	type	required	desc
image_url	body	string	✓	Adresse https publique à retirer

Exemple de code

curl -X POST "https://vivareel.ai/api/developer/v1/virtual-assets/remove" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://cdn.example/a.png"
}'

Exemple de corps de requête

{
  "image_url": "https://cdn.example/a.png"
}

Exemple de réponse

{
  "code": 200,
  "message": "已移出 Seedance 虚拟资产库",
  "data": {
    "asset_id": 321,
    "image_url": "https://cdn.example/a.png",
    "in_virtual_asset_library": false
  },
  "pagination": null
}