TokenLab

Tâches asynchrones

Obtenir le statut d'une tâche

Récupérez le statut et le résultat de toute tâche asynchrone : images, vidéo, musique, 3D, Worlds et transcription audio asynchrone

GET
/v1/tasks/{id}

Aperçu

Utilisez GET /v1/tasks/{id} pour vérifier n'importe quelle tâche asynchrone. Cela prend en charge les tâches d'image, de vidéo, de musique, de 3D, de Worlds et de transcription audio asynchrone. Transmettez l' id ou le task_id provenant de la réponse de création.

Les champs de résultat World, tels que world_id et world_marble_url, sont documentés dans Obtenir le statut d'un World. Pour une tâche World, X-Task-Type est 3d.

Pour la plupart des tâches, le poll_url dans la réponse de création est ce même chemin. Une réponse de création Worlds renvoie un poll_url sous /v1/worlds/generations/{id} ; interrogez /v1/tasks/{id} avec l' id de la tâche pour les Worlds également.

Les chemins de statut par modalité, tels que /v1/images/{id}, /v1/videos/generations/{id}, /v1/music/generations/{id} et /v1/3d/generations/{id}, sont des points de terminaison de compatibilité. Ils restent pris en charge pour les intégrations existantes.

Une lecture de statut renvoie HTTP 200 pour une tâche ayant échoué. Lisez status, et non le code HTTP, pour voir le résultat. Les champs de résultat dépendent du type de tâche ; voir Obtenir le statut d'une image, Obtenir le statut d'une vidéo, Obtenir le statut d'une musique et Obtenir le statut 3D. Les liens de résultat sont des URL de résultats multimédias TokenLab qui restent valides pendant 30 jours ; voir Rétention des données.

Paramètres de chemin

idstringpathrequis

L' id ou le task_id renvoyé par la requête de création.

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.

idstring

Identifiant canonique de la tâche asynchrone.

task_idstring

Alias de l'identifiant de la tâche asynchrone.

poll_urlstring

URL de statut pour cette tâche. Interrogez GET /v1/tasks/{id} avec id.

billing_transaction_idstring

ID de transaction de facturation, lorsqu'il est enregistré pour la tâche. L'en-tête X-Billing-Transaction-ID porte la même valeur. Il s'agit d'un identifiant de facturation, pas d'un identifiant de tâche.

statusstring

Statut de la tâche : pending, processing, completed, failed ou timeout. Arrêtez l'interrogation à completed, failed ou timeout. Les tâches annulées sont représentées comme failed avec cancelled: true.

cancelledboolean

true lorsqu'une tâche asynchrone en file d'attente a été annulée avant son exécution.

cancellation_statusstring

Marqueur d'annulation. Présent en tant que cancelled lorsque l'annulation réussit.

dataarray

Pour les tâches d'image terminées, les résultats d'image générés sont renvoyés ici. Les tâches d'image renvoient des URL dans data[].url.

progressnumber

Valeur de progression optionnelle. Renvoyée uniquement lorsqu'une valeur de progression réelle est disponible ; utilisez status pour déterminer l'achèvement.

video_urlstring

URL de l'actif de résultat lorsque la tâche est terminée et produit une vidéo.

videoobject

Charge utile vidéo unique avec url, duration, width et height lorsqu'ils sont disponibles.

videosarray

Charges utiles vidéo multiples lorsque plus d'une sortie est disponible.

errorstring | object

Pourquoi la tâche a échoué : une chaîne de caractères, ou un objet avec message et, lorsqu'ils sont connus, type, code, param et retryable.

error_detailsobject

Détails de l'échec lorsque la tâche a échoué : status, message, type, code, retryable et param lorsqu'un champ de requête est en cause.

media_retentionobject

Statut de sauvegarde des liens de résultat : days et items[] avec url, kind, status et expires_at. Il peut être absent ; les liens fonctionnent toujours.

createdinteger

Horodatage de création lorsqu'il est disponible.

updatedinteger

Horodatage de la dernière mise à jour lorsqu'il est disponible.

modelstring

Modèle utilisé par la tâche lorsqu'il est disponible.

En-têtes de réponse

Les réponses de statut réussies incluent ces en-têtes :

En-têteDescription
X-Task-IDID de tâche public
X-Task-TypeFamille de tâche, telle que image, video, music, 3d ou audio
Cache-Controlno-store. Ne pas mettre en cache les réponses de statut
X-Billing-Transaction-IDID de transaction de facturation, lorsqu'il est enregistré
X-Task-CostCoût de la tâche réglé, lorsque la tâche est réglée

Comportement en cas d'erreur

HTTPCodeSignification
400missing_task_id, invalid_task_idL'ID de tâche est manquant ou n'est pas un ID de tâche valide
403task_not_ownedLa tâche n'appartient pas à l'espace de travail de cette clé API. Arrêtez de l'interroger
404async_task_not_foundLa tâche a expiré ou n'est pas disponible
503async_task_owner_unavailableLa tâche ne peut pas être lue pour le moment. Réessayez
{
  "error": {
    "message": "Task not found or no longer available.",
    "type": "invalid_request_error",
    "code": "async_task_not_found"
  }
}

Exemples

Requête

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"
{  "id": "string",  "status": "pending",  "progress": 0,  "created": 0,  "updated": 0,  "model": "string",  "video": {    "url": "string",    "duration": 0,    "width": 0,    "height": 0  },  "error": "string",  "error_details": {    "projection_version": 0,    "status": 400,    "message": "string",    "type": "string",    "code": "string",    "param": "string",    "retryable": true,    "upstream": {      "source": "string",      "code": "string",      "message": "string",      "param": "string"    }  },  "task_id": "string",  "poll_url": "string",  "cancelled": true,  "cancellation_status": "cancelled",  "billing_transaction_id": "string",  "video_url": "string",  "last_frame_url": "string",  "videos": [    {}  ],  "data": [    {}  ],  "audio_url": "string",  "title": "string",  "lyrics": "string",  "model_url": "string",  "glb_url": "string",  "fbx_url": "string",  "media_retention": {    "days": 0,    "items": [      {        "url": "http://example.com",        "kind": "image",        "content_type": "string",        "status": "saving",        "expires_at": "2019-08-24T14:15:22Z"      }    ]  }}

Autorisation

BearerAuth
AuthorizationBearer <token>

Authentification par clé API. Créez ou gérez vos clés API dans Dashboard > API > API Keys.

Emplacement: header

Paramètres de chemin

id*string

L'ID de tâche asynchrone renvoyé par id / task_id, ou intégré dans poll_url

Réponse

application/json

application/json

application/json

application/json

application/json

application/json

application/json