Interroger une tâche vidéo

Après avoir créé une tâche, utilisez l'id de la réponse de création pour consulter sa progression et son résultat ; pour la création, voir Créer une tâche vidéo.

Consultation du statut : GET /v1/video/generations/{task_id}

Téléchargement de la vidéo finale : GET /v1/videos/{task_id}/content

Une fois la tâche terminée, l'interface de consultation renvoie l'adresse de la vidéo dans metadata.url. La plateforme privilégie l'adresse vidéo d'origine en amont et ne se rabat sur une adresse d'artefact de la plateforme avec capacité access que si l'amont ne fournit aucune adresse utilisable. L'adresse d'origine en amont peut comporter une signature et une date d'expiration ; elle peut être ouverte directement dans un navigateur ou un lecteur ; les adresses d'artefacts de la plateforme fonctionnent également. Vous pouvez aussi appeler /v1/videos/{task_id}/content avec la clé API pour télécharger le fichier vidéo.

Méthode d'authentification

Authorization: Bearer <API_KEY>.

Paramètres de requête · path

Exemple de requête

curl "$LOCOPAL_API_ORIGIN/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Télécharger la vidéo

Une fois le statut de la tâche passé à completed, utilisez directement le metadata.url de la réponse de consultation :

curl -L "$LOCOPAL_API_ORIGIN/v1/videos/$LOCOPAL_TASK_ID/content" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -o "$LOCOPAL_TASK_ID.mp4"

Paramètres de réponse

Corps de réponse

En cours d'exécution :

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1787299277
}

Génération réussie :

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "completed",
  "progress": 100,
  "created_at": 1787299277,
  "completed_at": 1787299581,
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800,
  "metadata": {
    "url": "https://upstream.example.com/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO.mp4?signature=...",
    "upstream_created": true
  },
  "usage": {
    "prompt_tokens": 141034,
    "completion_tokens": 0,
    "total_tokens": 141034,
    "quota": 2789652,
    "amount": 5.579304,
    "currency": "CNY"
  }
}

usage n'est renvoyé qu'après le règlement de la tâche, et ses valeurs correspondent exactement au débit de cette tâche sur la facture : usage.quota est le nombre de crédits consommés, usage.amount est le montant en CNY converti depuis ces crédits selon le taux du site actuel, et usage.total_tokens est le nombre de tokens vidéo facturés. Tant que la tâche est en file d'attente ou en génération, usage n'est pas renvoyé ; ne déduisez pas les frais de la réponse de consultation. Pour vérifier le débit, comparez usage.quota et usage.amount dans la facture de la console avec le même id.

metadata.url peut être une adresse amont signée ou une adresse fournie en repli par l'interface d'artefacts de la plateforme. Traitez-la comme un identifiant sensible et ne la partagez pas publiquement. Une fois la vidéo générée, il est recommandé de la télécharger ou de la copier dans votre propre stockage objet avant expires_at.

Artefacts vidéo et aperçu

Outre la lecture directe de metadata.url, vous pouvez aussi consulter la liste des artefacts de la plateforme :

curl "$LOCOPAL_API_ORIGIN/v1/tasks/$LOCOPAL_TASK_ID/artifacts" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Une fois la tâche terminée, renvoie :

{
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "artifacts": [
    {
      "key": "video",
      "type": "video",
      "content_url": "https://locopalai.com/v1/tasks/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO/artifacts/video/content?access=..."
    }
  ]
}

L'adresse de contenu d'un artefact prend en charge les requêtes Range ; les lecteurs, l'aperçu dans le navigateur et les téléchargements reprenables peuvent l'utiliser directement. Si le client ne lit que metadata.url, continuez à utiliser la logique existante ; nul besoin de passer à l'interface d'artefacts.

Échec de la génération :

{
  "id": "task_NlersigX6rIqiOjCwTFlgNmGMTwqt39K",
  "object": "video",
  "model": "doubao-seedance-2.0-D",
  "status": "failed",
  "progress": 100,
  "created_at": 1789971935,
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  },
  "metadata": {
    "submission_stage": "submitting",
    "upstream_created": false
  }
}

error.message est le texte d'échec final mis en forme par la plateforme. Même si une tâche historique a initialement stocké un JSON imbriqué, la consultation renvoie du texte normalisé ; l'appelant peut afficher directement ce champ à l'utilisateur, sans recombiner ni analyser le JSON amont d'origine côté client.

Réponse d'erreur

Consulter un ID de tâche inexistant (ou une tâche n'appartenant pas au compte actuel) renvoie HTTP 400 :

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

Gestion des statuts

Le client ne doit pas se fier à un nombre fixe de secondes d'attente pour déterminer l'achèvement, ni recréer la tâche à cause d'un seul délai réseau dépassé ; il est recommandé d'interroger toutes les 5 à 15 secondes.

Échec de lecture des ressources de référence

Lorsque l'erreur pointe vers content[n].image_url, video_url ou contient resource download failed, localisez d'abord l'élément précis par son indice de tableau, puis vérifiez :

1. l'URL peut-elle être GET directement depuis l'internet public et renvoyer 200 ;
2. redirige-t-elle vers une page de connexion, ou dépend-elle de Cookie, de Referer ou d'une liste blanche d'IP ;
3. le Content-Type correspond-il au format réel du fichier ;
4. l'URL signée temporaire reste-t-elle valide pendant le téléchargement et le traitement ;
5. la ressource asset:// appartient-elle au compte actuel et est-elle à l'état Active ;
6. le modèle actuel prend-il en charge ce type et ce nombre de ressources.

Après correction des ressources, recréez la tâche. Pour le message d'erreur, affichez une seule fois une raison lisible à l'utilisateur, sans recombiner ni exposer à plusieurs reprises du JSON échappé sur plusieurs niveaux.

Concurrence, nouvelles tentatives et facturation

• différentes tâches vidéo peuvent être créées en concurrence ;
• une même réponse de création doit être consultée avec le même ID de tâche ;
• ne lancez une nouvelle requête de création que lorsque la tâche a échoué explicitement et que l'utilisateur réessaie volontairement ;
• la facturation est détaillée selon le modèle, la résolution, la durée et les entrées de vidéo de référence ; fiez-vous à la place de marché des modèles et à la facture finale. Un échec de validation des paramètres (400) signifie que la requête n'a pas été acceptée et n'entraîne généralement pas de frais de tâche de génération.

Documentation associée