非同期ジョブ

タスクステータスの取得

画像、動画、音楽、3D、Worlds、および非同期音声文字起こしを含む、あらゆる非同期タスクのステータスと結果を取得します

GET
/v1/tasks/{id}

概要

GET /v1/tasks/{id} を使用して、任意の非同期タスクを確認します。このエンドポイントは、画像、動画、音楽、3D、Worlds、および非同期音声文字起こしの各タスクに対応しています。作成時のレスポンスに含まれる id または task_id を渡してください。

world_id や world_marble_url などの World 結果フィールドについては、ワールドステータスの取得 を参照してください。World タスクの場合、X-Task-Type は 3d となります。

ほとんどのタスクにおいて、作成時のレスポンスに含まれる poll_url はこのパスと同じです。Worlds の作成レスポンスは /v1/worlds/generations/{id} 配下の poll_url を返しますが、Worlds の場合もタスクの id を使用して /v1/tasks/{id} をポーリングしてください。

/v1/images/{id}、/v1/videos/generations/{id}、/v1/music/generations/{id}、/v1/3d/generations/{id} といったモダリティごとのステータスパスは、互換性のためのエンドポイントです。これらは既存のインテグレーションのために引き続きサポートされます。

タスクが失敗した場合でも、ステータス読み取りは HTTP 200 を返します。結果を確認するには HTTP コードではなく status を読み取ってください。結果フィールドはタスクの種類によって異なります。画像ステータスの取得、動画ステータスの取得、音楽生成ステータスの取得、および Get 3D Status を参照してください。結果のリンクは TokenLab のメディア結果 URL であり、30日間有効です。データ保持 を参照してください。

パスパラメータ

idstringpath必須

作成リクエストによって返された id または task_id。

レスポンス

結果、エラー、タイムスタンプ、およびモデルを記述するフィールドは、タスクで利用可能な場合に返されます。

idstring

正規の非同期タスク識別子。

task_idstring

非同期タスク識別子のエイリアス。

poll_urlstring

このタスクのステータス URL。id を使用して GET /v1/tasks/{id} をポーリングします。

billing_transaction_idstring

タスクに対して記録された場合の課金トランザクション ID。X-Billing-Transaction-ID ヘッダーにも同じ値が含まれます。これはタスク識別子ではなく、課金識別子です。

statusstring

タスクのステータス: pending、processing、completed、failed、または timeout。completed、failed、または timeout になった時点でポーリングを停止してください。キャンセルされたタスクは、cancelled: true を伴う failed として表現されます。

cancelledboolean

キューに入れられた非同期タスクが実行前にキャンセルされた場合に true となります。

cancellation_statusstring

キャンセルマーカー。キャンセルが成功すると cancelled として表示されます。

dataarray

完了した画像タスクの場合、生成された画像結果がここに返されます。画像タスクは data[].url に URL を返します。

progressnumber

オプションの進捗値。実際の進捗値が利用可能な場合にのみ返されます。完了の判定には status を使用してください。

video_urlstring

タスクが完了し、動画が生成された際の結果アセット URL。

videoobject

利用可能な場合に url、duration、width、height を含む単一の動画ペイロード。

videosarray

複数の出力が利用可能な場合の複数の動画ペイロード。

errorstring | object

タスクが失敗した理由。文字列、または message を含み、判明している場合は type、code、param、retryable を含むオブジェクト。

error_detailsobject

タスクが失敗した際の詳細情報。status、message、type、code、retryable、およびリクエストフィールドに問題がある場合は param が含まれます。

media_retentionobject

結果リンクの保存ステータス。days、および url、kind、status、expires_at を含む items[]。存在しない場合もありますが、リンクは引き続き機能します。

createdinteger

利用可能な場合の作成タイムスタンプ。

updatedinteger

利用可能な場合の最終更新タイムスタンプ。

modelstring

利用可能な場合にタスクで使用されたモデル。

レスポンスヘッダー

成功したステータスレスポンスには、以下のヘッダーが含まれます。

ヘッダー説明
X-Task-ID公開タスク ID
X-Task-Typeimage、video、music、3d、または audio などのタスクファミリー
Cache-Controlno-store。ステータスレスポンスをキャッシュしないでください
X-Billing-Transaction-ID記録されている場合の課金トランザクション ID
X-Task-Costタスクが決済済みの場合の確定したタスクコスト

エラー動作

HTTPコード意味
400missing_task_id, invalid_task_idタスク ID が欠落しているか、有効なタスク ID ではありません
403task_not_ownedタスクはこの API キーのワークスペースに属していません。ポーリングを停止してください
404async_task_not_foundタスクの有効期限が切れているか、利用できません
503async_task_owner_unavailable現在タスクを読み取ることができません。再試行してください
{
  "error": {
    "message": "Task not found or no longer available.",
    "type": "invalid_request_error",
    "code": "async_task_not_found"
  }
}

例

リクエスト

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"      }    ]  }}

認証

BearerAuth
AuthorizationBearer <token>

APIキー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。

場所: header

パスパラメータ

id*string

id / task_id によって返される、または poll_url に埋め込まれた非同期タスクID

レスポンス

application/json

application/json

application/json

application/json

application/json

application/json

application/json