Guides médias
Génération de vidéo
Créez des vidéos à partir de texte, d'images, d'audio ou de clips existants
La génération de vidéo est asynchrone. POST /v1/videos/generations renvoie un ID de tâche et généralement une poll_url. Interrogez GET /v1/tasks/{id} avec cet ID jusqu'à ce que la vidéo soit prête.
Envoyez des URL HTTP(S) publiques ou des URL de données prises en charge dans les champs d'image acceptés par le modèle sélectionné. Ces entrées suivent le chemin média normal et ne créent pas automatiquement d'identifiants de matériel réutilisables.
Lorsqu'un matériel explicite est encore en cours de préparation, POST /v1/videos/generations renvoie 409 seedance_material_preparing avec des inactive_asset_ids. Interrogez ces ressources jusqu'à ce qu'elles soient ACTIVE, puis réessayez avec les mêmes identifiants de matériel. Si une ressource est FAILED, inspectez le error_message et corrigez-la ou réimportez-la avant de réessayer.
Choisir une API
Utilisez /v1/videos/generations pour une nouvelle intégration vidéo. Les clients Seedance 2.0 existants qui envoient déjà des requêtes content[] Volcengine ou Action peuvent conserver ce format via /api/v3. Les deux API utilisent une clé Bearer TokenLab, mais leurs champs et valeurs de statut diffèrent.
Choisir ce qu'il faut créer
Définissez operation explicitement afin que l'API puisse valider les champs appropriés pour la tâche.
| Opération | Entrée requise ou typique | Cas d'utilisation |
|---|---|---|
text-to-video | prompt | Générer à partir de texte uniquement |
image-to-video | image_url ou image compatible | Animer une image de départ |
reference-to-video | reference_images et video_urls / audio_urls optionnels sur les modèles pris en charge | Conserver l'identité, le style ou les références d'actifs |
start-end-to-video | start_image, end_image | Contrôler la première et la dernière image |
video-to-video | video_url ou task_id spécifique au modèle | Transformer ou mettre à l'échelle un clip existant |
motion-control | image_url plus video_url | Appliquer une référence de mouvement à un sujet |
audio-to-video | audio_url | Flux vidéo conditionnés par l'audio |
video-extension | task_id, extend_at, ou champs d'extension spécifiques au modèle | Continuer une vidéo générée |
Choisir un modèle
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
-H "Authorization: Bearer sk-your-api-key"Utilisez un ID de modèle renvoyé par TokenLab, puis choisissez le type de génération avec operation et les entrées média correspondantes. N'utilisez pas un nom d'opération comme ID de modèle.
Lisez les détails du modèle sélectionné avant de vous appuyer sur des champs spécialisés tels que reference_images, kling_elements, output_audio, duration, resolution ou aspect_ratio.
Créer une vidéo
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"operation": "text-to-video",
"prompt": "A calm cinematic shot of a cat walking through a sunlit garden",
"resolution": "720p",
"duration": 4,
"aspect_ratio": "16:9"
}'Utilisez des URL https pour les médias pouvant être récupérés sur Internet. Les URL temporaires doivent rester valides jusqu'à ce que TokenLab crée la tâche.
Champs spécifiques au modèle
Le comportement audio dépend du modèle sélectionné et de l'opération. Une vidéo peut contenir du son même lorsqu'aucun sélecteur audio n'est exposé. Omettre un sélecteur est différent de l'envoi de false.
veo3.1,veo3.1-fastetveo3.1-litegénèrent toujours de l'audio. Omettezoutput_audioou envoyeztrue;falseest rejeté.wan-2.6etwan-2.7incluent toujours de l'audio. Omettezoutput_audioou envoyeztrue.wan-3.0etwan-3.0-primeincluent également toujours de l'audio et ne prennent aucun sélecteur audio.hailuo-h3génère de l'audio natif et ne possède pas d'interrupteur de sourdine. N'envoyez pas de sélecteur audio qui ne figure pas dans les détails du modèle.viduq3-proetviduq3-turbogénèrent de l'audio par défaut ; envoyezoutput_audio: false(ouaudio: false) pour une sortie silencieuse. Les modèles Seedance et PixVerse prennentoutput_audio; envoyez-le explicitement au lieu de vous fier à la valeur par défaut. Utilisez-le uniquement pour les opérations qui le listent.audio_url/audio_urlsfournissent une entrée ou une référence audio. Ce ne sont pas des commutateurs de sortie audio. Le montage vidéo, le transfert de mouvement et le transfert de style peuvent conserver la bande sonore d'entrée ; préserver l'audio source ne signifie pas le mettre en sourdine.
Consultez les détails du modèle pour connaître les valeurs autorisées et les tarifs dépendants de l'audio. Lorsque les détails d'un modèle les listent, les alias outputAudio, generate_audio et le booléen audio doivent être cohérents avec output_audio lorsqu'ils sont combinés. Ne supposez pas que chaque version ou opération d'une famille de modèles partage les mêmes contrôles audio.
- Pour la famille Seedance 2.0, lisez le guide des modèles vidéo Seedance 2.0 avant d'utiliser la sortie 4K, les plafonds de résolution Fast/Mini ou les entrées de référence multimodales.
- Pour
grok-imagine-video(vidéo vers vidéo), envoyez unpromptet unevideo_urlHTTPS publique au format.mp4. Une URL de résultat.mp4TokenLab provenant d'une tâche précédente fonctionne. Cette opération n'utilise pas les sélecteursduration,resolutionouaspect_ratio.
PixVerse et HappyHorse
| Modèle | Opérations | Entrées | Résolution | Durée | Sélecteur audio |
|---|---|---|---|---|---|
pixverse-c1, pixverse-v6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | prompt; image_url; start_image + end_image; reference_images | 360p, 540p, 720p, 1080p | Tout entier de 1 à 15 secondes | output_audio, false par défaut |
pixverse-v5.6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | Mêmes champs que C1 et V6 | 360p, 540p, 720p, 1080p | 5, 8 ou 10 secondes ; 1080p prend en charge 5 ou 8 secondes | output_audio, false par défaut |
happyhorse-1.0 | text-to-video, image-to-video, reference-to-video, video-to-video | prompt; image_url; reference_images; video_url + reference_images | 720p, 1080p | 3 à 15 secondes pour les opérations de génération ; la sortie video-to-video est limitée à 15 secondes | Ne pas envoyer output_audio |
Sur TokenLab, les modèles PixVerse ci-dessus n'acceptent pas operation=video-extension.
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "pixverse-v6",
"operation": "image-to-video",
"prompt": "A slow camera move through a neon-lit street",
"image_url": "https://example.com/start.jpg",
"resolution": "1080p",
"duration": 5,
"output_audio": true
}'Obtenir la vidéo terminée
Appelez GET /v1/tasks/{id} avec l'id ou le task_id de la réponse de création jusqu'à ce que la tâche soit completed ou failed.
Les tâches vidéo terminées peuvent renvoyer video_url, video ou videos selon le modèle et le nombre de sorties. Traitez billing_transaction_id comme un identifiant de facturation, et non comme un identifiant de tâche.
Les URL de résultat vidéo sont des URL de résultat média TokenLab qui se terminent par le type de fichier, tel que .mp4, et restent valides pendant 30 jours. media_retention.items rapporte le statut de sauvegarde de chaque élément et sa date d'expiration (expires_at) ; la réponse peut omettre media_retention lorsque le statut de sauvegarde n'est pas connu à temps, et l'URL fonctionne toujours. Les tâches échouées ou en cours renvoient des champs d'URL vidéo vides. Les instantanés de tâches asynchrones ont un cycle de vie distinct. Voir Rétention des données.
Pièges courants
- N'utilisez pas de chemins de statut par modalité tels que
/v1/videos/generations/{id}dans le nouveau code ; interrogezGET /v1/tasks/{id}. - Ne combinez pas les champs de première image avec des flux d'images de référence dédiés, sauf si les détails du modèle le permettent.
- Ne supposez pas que
durationdécrit la longueur de la vidéo de référence d'entrée ; elle contrôle généralement la longueur de la sortie générée. - Envoyez un
Idempotency-KeyavecPOST /v1/videos/generations. Après un délai d'attente, envoyez la même requête avec la même clé pour obtenir la tâche originale. Sans clé, vérifiez si une tâche a déjà été créée avant de réessayer.
Référence API
| Sujet | Référence |
|---|---|
| Créer une vidéo | Créer une vidéo |
| Obtenir le statut de la vidéo | Obtenir le statut de la vidéo |
| Obtenir le statut de la tâche | Obtenir le statut de la tâche |
| Annuler une tâche | Annuler une tâche |
| Facturation et tarification | Facturation et tarification |
Hailuo H3-Max génère des vidéos de 5 à 15 secondes en 480p ou 768p à partir de texte, d'une première image, ou d'une première et d'une dernière image. Son flux de travail axé sur la vitesse est utile pour transformer rapidement une idée de plan en un court clip.
{
"model": "hailuo-h3-max",
"operation": "text-to-video",
"prompt": "A slow camera move through a quiet garden",
"resolution": "768p",
"duration": 5,
"aspect_ratio": "16:9"
}