Vidéo & ressources
Créer une vidéo
Démarrer une tâche de génération vidéo
Aperçu
La génération vidéo est asynchrone. Une requête de création réussie renvoie un id de tâche (la même valeur que task_id) et une poll_url. Appelez GET /v1/tasks/{id} avec cet identifiant jusqu'à ce que le status soit completed ou failed, puis lisez video_url. Voir Obtenir le statut de la vidéo.
- Le fichier résultat est conservé pendant 30 jours. Téléchargez-le si vous en avez besoin plus longtemps ; voir Rétention des données.
- Une tâche Seedance en file d'attente peut être annulée avec Annuler une tâche.
- Le coût peut être réservé lorsque la tâche est acceptée et est réglé lorsque la tâche se termine ou échoue. Voir Facturation et tarification.
- Envoyez un en-tête
Idempotency-Keypour réessayer une requête de création en toute sécurité après un délai d'attente.
Chaque modèle accepte ses propres opérations et champs. GET /v1/models/{model} (Obtenir un modèle) liste, pour chaque opération, les champs acceptés, les résolutions, les durées et les formats d'image. Un champ ou une valeur en dehors de cette liste renvoie 400 avec les valeurs acceptées. Définissez vous-même duration, resolution, aspect_ratio et output_audio : si vous en omettez un, TokenLab utilise la valeur par défaut du modèle pour l'opération, et si aucune valeur par défaut ne correspond, la requête renvoie 400 et nomme le champ à définir.
Entrée audio et média
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.
Utilisez des URLs https accessibles publiquement pour les images, les vidéos et l'audio, et maintenez-les valides jusqu'au démarrage de la tâche. Une URL de média peut contenir jusqu'à 8 192 caractères. Certains modèles acceptent également des URLs d'image data: en ligne (jusqu'à 2 000 000 de caractères par champ) ; les URLs sont plus fiables pour les fichiers volumineux. Ne mélangez pas le base64 en ligne et les URLs distantes dans la même requête.
Corps de la requête
veo3.1ID du modèle vidéo. Listez les modèles vidéo actuels avec Lister les modèles (recommended_for=video), puis envoyez le modèle explicitement.
PixVerse
- Modèle:
pixverse-c1,pixverse-v6,pixverse-v5.6 - Opérations:
text-to-video,image-to-video,start-end-to-video,reference-to-video - Sélecteur audio:
output_audio,falsepar défaut
Sur TokenLab, les modèles PixVerse ci-dessus n'acceptent pas operation=video-extension.
HappyHorse
- Modèle:
happyhorse-1.0 - Opérations:
text-to-video,image-to-video,reference-to-video,video-to-video - Sélecteur audio: Ne pas envoyer
output_audio
Description textuelle de la vidéo, jusqu'à 10 000 caractères. La plupart des opérations en nécessitent une ; les détails du modèle indiquent celles qui n'en ont pas besoin.
Mode de génération : text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension ou motion-control. Chaque modèle ne prend en charge qu'une partie d'entre eux ; les autres renvoient 400 unsupported_operation. Si vous l'omettez, TokenLab le déduit à partir des entrées : un task_id avec extend_at ou extend_times donne video-extension, des images ou matériaux de référence donnent reference-to-video, end_image donne start-end-to-video, une entrée vidéo donne video-to-video, une entrée image (image, image_url, image_urls ou start_image) donne image-to-video, et sinon text-to-video. Envoyez-le explicitement afin qu'un champ non correspondant échoue rapidement.
URL accessible publiquement de l'image de la première frame. Les modèles Seedance 2.0 acceptent également asset://asset-YYYYMMDDHHMMSS-xxxxx pour utiliser un matériau TokenLab ACTIVE comme première frame. Préférez une URL https pour une prise en charge maximale par les modèles.
Image en ligne sous forme d'URL de données (par exemple, data:image/jpeg;base64,...). Seuls certains modèles l'acceptent ; image_url fonctionne sur un plus grand nombre.
URLs d'images pour les modèles qui listent ce champ. Voir reference_images pour les limites de nombre.
Images de référence pour reference-to-video, sous forme d'URLs https ou d'URLs de données. La limite de nombre dépend du modèle :
seedance-2.0,seedance-2.0-fastetseedance-2.0-mini: jusqu'à 9 références d'image au total, incluant les matériaux. Plus renvoie400 too_many_seedance_reference_images.seedance-2.5: jusqu'à 30 entrées d'image au total viaimage_urlsetreference_images.grok-imagine-video: jusqu'à 7, et ladurationest plafonnée à 10 secondes.grok-imagine-video-1.5etgrok-imagine-video-1.5-previewne prennent aucune image de référence.- Autres modèles : voir les détails du modèle. Une requête dépassant la limite renvoie
400 too_many_items.
Les modèles Seedance 2.0 acceptent également asset://asset-YYYYMMDDHHMMSS-xxxxx pour un matériau TokenLab ACTIVE. Pour la sélection de modèle, les limites 4K et les notes Mini, voir le guide des modèles vidéo Seedance 2.0. Pour grok-imagine-video, ne combinez pas d'images de référence avec image_url ou image.
Image de la première trame. Avec end_image, la requête est start-end-to-video. Sans end_image, il s'agit de image-to-video, et start_image fonctionne comme image sur les modèles dont le contrat le mentionne. Accepte une URL publique ou une URL de données ; les modèles Seedance 2.0 acceptent également asset://asset-YYYYMMDDHHMMSS-xxxxx.
Image de la dernière frame pour start-end-to-video. Accepte les mêmes entrées que start_image.
ID de matériau TokenLab Seedance renvoyé par Créer un matériau. Accepté uniquement par les modèles Seedance 2.0 ; les autres modèles renvoient 400 unsupported_seedance_material_asset_model. Le matériau doit être ACTIVE et appartenir à votre compte. Ce champ est une entrée de référence générique ; pour assigner explicitement une signification de première frame, dernière frame ou image de référence, mettez asset://<material_asset_id> dans start_image, end_image ou reference_images à la place.
Jusqu'à 9 IDs de matériaux TokenLab Seedance. Ils comptent dans les 9 références d'image des modèles Seedance 2.0.
Les URLs d'image ordinaires sont transmises comme entrées d'image ; elles ne créent pas de matériaux réutilisables. Créez des matériaux réutilisables via l'API de matériaux, puis utilisez leurs IDs TokenLab ou leurs URIs asset://asset-YYYYMMDDHHMMSS-xxxxx. Si un matériau explicite renvoie 409 seedance_material_preparing, vérifiez les inactive_asset_ids renvoyés et réessayez une fois que ces matériaux sont devenus ACTIVE.
URL accessible publiquement de la vidéo source, pour les opérations qui en acceptent une : video-to-video, video-extension et motion-control, sur les modèles qui listent ce champ.
Vidéos source ou de référence pour les modèles qui listent ce champ. seedance-2.5 accepte jusqu'à 10 entrées vidéo au total via video_url et video_urls. Voir les détails du modèle pour les autres modèles.
URL audio publique pour une référence audio ou une opération pilotée par l'audio, sur les modèles qui listent ce champ. Il s'agit d'une entrée, pas d'un commutateur de sortie audio.
Audio de référence pour les modèles qui listent ce champ. seedance-2.5 accepte jusqu'à 10 entrées audio au total via audio_url et audio_urls et autorise une requête avec des références audio sans prompt. Pour seedance-2.5, l'audio de référence plus la vidéo de référence dure au maximum 30 secondes combinées.
ID d'une tâche précédente dans votre espace de travail, pour video-extension sur les modèles qui listent ce champ. Une tâche qui n'appartient pas à votre espace de travail renvoie 403 task_not_owned.
Seconde de la vidéo source où commence une video-extension. Requis par grok-imagine-video.
Secondes à ajouter dans une video-extension, sur les modèles qui listent ce champ. grok-imagine-video accepte 6 ou 10.
Durée de sortie en secondes. Les valeurs autorisées dépendent du modèle et de l'opération ; les autres valeurs renvoient 400 invalid_duration. Les modèles Seedance acceptent également -1 pour laisser le modèle choisir dans sa plage ; la facturation est alors estimée de manière conservatrice jusqu'à ce que la tâche se termine. Certaines opérations ne prennent pas de durée, comme motion-control et grok-imagine-video en mode video-to-video.
Alias de compatibilité pour duration. Si les deux sont envoyés, ils doivent être identiques.
Format d'image, par exemple 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 ou adaptive (Seedance). Les valeurs autorisées dépendent du modèle et de l'opération ; les autres valeurs renvoient 400 invalid_aspect_ratio.
Résolution de sortie, par exemple 480p, 720p, 1080p ou 4k. Les valeurs autorisées dépendent du modèle et de l'opération, et certains modèles utilisent également 360p, 540p ou 768p. Les autres valeurs renvoient 400 invalid_resolution.
Sélecteur de sortie audio pour les opérations qui le listent. L'omission suit la valeur par défaut du modèle ; false demande une sortie silencieuse uniquement là où le modèle l'autorise. Voir les notes audio ci-dessus et les détails du modèle sélectionné.
Format de conteneur, mp4 ou mov, pour les modèles qui listent ce champ, comme seedance-2.5. Omettez-le pour les modèles qui ne le listent pas.
Renvoie également la dernière frame générée sous forme de last_frame_url. Modèles Seedance uniquement.
Basculement du filigrane pour les modèles qui listent ce champ (modèles Seedance).
Ce qu'il faut éviter dans la vidéo générée, jusqu'à 5 000 caractères, pour les modèles qui listent ce champ.
Graine pour une génération reproductible, pour les modèles qui listent ce champ. Les modèles Seedance 2.0 acceptent -1 pour une graine aléatoire ; seedance-2.5 n'accepte pas ce champ.
Frames par seconde (1-120), pour les modèles qui listent ce champ.
Nombre de frames, pour les modèles qui listent ce champ. Les modèles Seedance ne l'acceptent pas.
Secondes pendant lesquelles la tâche peut attendre dans la file d'attente avant d'expirer (3600 à 259200), pour les modèles Seedance.
Priorité de la tâche de 0 à 9, pour les modèles Seedance. Ne le combinez pas avec service_tier=flex.
default est accepté comme une opération sans effet de compatibilité sur les modèles Seedance 2.0 et 2.5. flex est rejeté sur ces modèles.
Identifiant de sécurité de l'utilisateur final (jusqu'à 128 caractères), pour les modèles Seedance. S'il est omis, TokenLab utilise user lorsqu'il est fourni.
Outils que le modèle peut utiliser pendant la génération, pour les modèles Seedance 2.0 et 2.5. L'outil pris en charge est {"type": "web_search"}.
Un identifiant unique pour l'utilisateur final. Pour les modèles Seedance, TokenLab l'utilise également comme safety_identifier lorsque ce champ est omis.
Noms de champs compatibles
- Les champs principaux utilisent le
snake_case:aspect_ratio,output_audioetreference_images. - Pour la compatibilité, TokenLab accepte également
ratio,generate_audio,outputAudio,secondsetreferenceImages. - Si un champ principal et son alias sont tous deux envoyés, leurs valeurs doivent correspondre. Une discordance renvoie
400avecconflicting_audio_selector,conflicting_durationouconflicting_aspect_ratio.
Paramètres Seedance
Les modèles Seedance (seedance-2.0, seedance-2.0-fast, seedance-2.0-mini et seedance-2.5) prennent les noms de champs TokenLab ci-dessus et les alias seconds, ratio et generate_audio. Les versions diffèrent :
| Modèles Seedance 2.0 | seedance-2.5 | |
|---|---|---|
| Résolution | seedance-2.0 : 480p, 720p, 1080p, 4k. seedance-2.0-fast et seedance-2.0-mini : 480p, 720p | 480p, 720p |
| Durée | -1, 4 à 15 secondes | -1, 4 à 30 secondes |
| Format d'image | 1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptive | Identique pour text-to-video et reference-to-video. Image-to-video, start-end, édition vidéo et extension nécessitent adaptive ; l'édition vidéo nécessite également duration=-1 |
| Format de sortie | mp4 | mp4 ou mov |
seed | Accepté | Non accepté |
| Entrées de référence | 9 références d'image incluant les matériaux (les matériaux ne sont acceptés que sur ces modèles) | 30 images, 10 vidéos et 10 fichiers audio au total |
Les détails du modèle sont la source actuelle pour ces valeurs. Envoyez duration, resolution, aspect_ratio et output_audio explicitement au lieu de vous fier à une valeur par défaut ; le recommended_request du modèle montre une requête typique.
duration=-1 ou seconds=-1 permet à Seedance de choisir la durée de sortie dans la plage du modèle. TokenLab estime le coût de manière conservatrice avant que la tâche ne se termine, puis règle à partir de l'utilisation de la tâche terminée lorsqu'elle est disponible. service_tier=flex et frames sont rejetés sur ces modèles.
Exemple Seedance
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"prompt": "A sleek product reveal with cinematic camera movement",
"operation": "text-to-video",
"duration": -1,
"aspect_ratio": "adaptive",
"resolution": "720p",
"output_audio": true
}'Réponse
Les champs décrivant les résultats, les erreurs, les horodatages et le modèle sont renvoyés lorsqu'ils sont disponibles pour la tâche.
ID de la tâche. Identique à task_id.
ID de la tâche à interroger avec GET /v1/tasks/{id}.
URL de statut pour cette tâche, /v1/tasks/{id}. Appelez-la avec votre clé API.
Statut de la tâche : pending, processing, completed, failed. Une nouvelle tâche est normalement pending.
Horodatage Unix de création de la tâche.
Modèle utilisé.
ID de transaction de facturation lorsque le règlement est déjà terminé. Il est distinct de l'ID de la tâche.
URL de la vidéo, présente uniquement lorsque la réponse de création contient déjà le résultat. Normalement, vous la lisez à partir de la réponse de statut.
Message d'erreur ou objet d'erreur structuré lorsque la tâche échoue.
Erreurs
| Statut et code | Signification |
|---|---|
400 invalid_request | Un champ est mal formé, hors plage ou manquant. error.param le nomme. Un message tel que "Set aspect_ratio explicitly" signifie que le champ omis n'a pas de valeur par défaut pour cette requête. |
400 unsupported_operation, unsupported_parameter, invalid_resolution, invalid_duration, invalid_aspect_ratio, invalid_parameter_value, too_many_items, prompt_too_long | La requête ne correspond pas à ce que le modèle accepte pour l'opération. L'erreur liste généralement les valeurs acceptées. |
400 invalid_parameter | Une entrée ne correspond pas à l'opération, par exemple une image envoyée avec text-to-video. |
400 conflicting_audio_selector, conflicting_duration, conflicting_aspect_ratio | Un alias et son champ principal sont en désaccord. |
400 unpriceable_selection | La combinaison sélectionnée n'a pas de prix. Modifiez resolution, duration, aspect_ratio ou le réglage audio. |
400 too_many_seedance_reference_images, unsupported_seedance_material_asset_model | Trop de références d'image pour un modèle Seedance 2.0, ou un matériau envoyé à un autre modèle. |
402 | Solde insuffisant. |
403 task_not_owned | Le task_id appartient à un autre espace de travail. |
409 seedance_material_preparing, seedance_material_route_unavailable | Un matériau n'est pas encore ACTIVE, ou le modèle sélectionné ne peut pas utiliser les matériaux fournis. |
429 | Limite de débit dépassée. Voir Limites de débit. |
Requête
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"prompt": "A cat walking through a garden, cinematic lighting",
"operation": "text-to-video",
"duration": 4,
"resolution": "720p",
"aspect_ratio": "16:9"
}'Réponse
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"model": "veo3.1",
"created": 1706000000
}Image vers vidéo
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "hailuo-2.3",
"prompt": "The scene begins from the provided image and adds gentle natural motion.",
"operation": "image-to-video",
"image_url": "https://example.com/image.jpg",
"duration": 6,
"resolution": "768p"
}
)Référence vers vidéo
Utilisez operation=reference-to-video lorsque le modèle prend en charge un conditionnement de référence dédié. Les références d'image vont dans reference_images ; les modèles qui prennent des vidéos et de l'audio de référence utilisent video_urls et audio_urls. duration définit uniquement la longueur de la sortie générée. Elle ne limite pas la longueur de l'entrée vidéo de référence. Voir reference_images ci-dessus pour les limites de nombre par modèle.
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "veo3.1",
"prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
"operation": "reference-to-video",
"reference_images": [
"https://example.com/ref-a.jpg",
"https://example.com/ref-b.jpg"
],
"duration": 8,
"resolution": "720p",
"aspect_ratio": "9:16"
}
)Contrôle des images clés
Utilisez start_image et end_image pour contrôler les première et dernière frames :
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "viduq2-pro",
"operation": "start-end-to-video",
"start_image": "https://example.com/day.jpg",
"end_image": "https://example.com/night.jpg",
"duration": 5,
"resolution": "720p"
}
)Vidéo vers vidéo
Utilisez operation=video-to-video lorsque le modèle accepte une vidéo existante comme entrée principale. Pour grok-imagine-video, envoyez une URL .mp4 HTTPS publique dans video_url et le prompt d'édition, et omettez resolution, duration et aspect_ratio.
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "grok-imagine-video",
"operation": "video-to-video",
"video_url": "https://example.com/source.mp4",
"prompt": "Enhance the clip while preserving the original motion."
}
)Extension vidéo
Utilisez operation=video-extension pour continuer un résultat précédent. Envoyez le task_id d'une tâche de votre espace de travail et un prompt ; les autres champs dépendent du modèle. grok-imagine-video nécessite également extend_at et accepte extend_times de 6 ou 10. veo3.1 et veo3.1-fast prennent task_id et prompt. Les modèles Seedance listent video_url, video_urls et task_id pour cette opération.
Contrôle de mouvement
Utilisez operation=motion-control lorsque le modèle attend à la fois une image de sujet et une vidéo de référence de mouvement. Envoyez image_url et video_url ; resolution est requise.
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "kling-3.0-motion-control",
"operation": "motion-control",
"prompt": "Keep the subject identity stable while following the motion reference.",
"image_url": "https://example.com/subject.png",
"video_url": "https://example.com/motion.mp4",
"resolution": "720p"
}
)Découverte de modèles
L'inventaire vidéo public et les opérations prises en charge changent avec le temps. Utilisez l'API des modèles pour vérifier la prise en charge actuelle avant de configurer un flux spécifique au modèle :
curl "https://api.tokenlab.sh/v1/models?recommended_for=video"
curl "https://api.tokenlab.sh/v1/models/veo3.1"Lisez la réponse détaillée du modèle avant de vous fier à des opérations ou des champs spécifiques au modèle. Les opérations telles que video-extension et motion-control sont spécifiques au modèle ; confirmez la disponibilité actuelle à cet endroit au lieu de vous fier aux exemples statiques de cette page.
Autorisation
BearerAuth Authentification par clé API. Créez ou gérez vos clés API dans Dashboard > API > API Keys.
Emplacement: header
En-têtes
Politique de livraison par requête. Remplace les valeurs par défaut de la clé API et de l'espace de travail. Tente automatiquement TokenLab Verified en premier et peut basculer une fois vers Official uniquement avant la sortie, l'acceptation de la requête ou la création de ressource persistante.
Valeurs possibles
- "auto"
- "verified"
- "official"
Clé optionnelle qui permet de réessayer une requête de création en toute sécurité. Envoyez une nouvelle valeur unique, telle qu'un UUID, pour chaque tâche. Une tentative avec la même clé et le même corps renvoie le résultat de la requête de création initiale, généralement la tâche d'origine, et ne crée, ne distribue ni ne facture une seconde tâche. Un corps différent avec une clé déjà acceptée est rejeté avec 409. Une clé de plus de 255 caractères est ignorée, et la requête ne bénéficie alors d'aucune protection d'idempotence. Voir Réessayer en toute sécurité avec une clé d'idempotence.
1 <= length <= 255Corps de la requête
application/json
Réponse
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json