ビデオと素材

動画ステータスの取得

動画タスクのステータスと結果を取得します

GET
/v1/tasks/{id}

GET /v1/videos/generations/{id} は互換性維持のためのエンドポイントです。既存のインテグレーション向けに引き続きサポートされており、GET /v1/tasks/{id} と同じ形式で結果を返します。新規のインテグレーションでは GET /v1/tasks/{id} をポーリングしてください。詳細は タスクステータスの取得 を参照してください。

パスパラメータ

idstringpath必須

動画作成リクエストによって返されたタスクIDです。id と task_id は同一のタスクを指します。

タスクが失敗した場合でも、ステータスの読み取りは HTTP 200 を返します。status を確認してください。期限切れまたは利用不可能なタスクは 404 async_task_not_found を返します。自身のワークスペースに属さないタスクは 403 task_not_owned を返します。503 async_task_owner_unavailable は一時的なエラーです。リクエストを再試行してください。

レスポンス

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

idstring

タスクID。

task_idstring

id と同じタスクID。

poll_urlstring

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

billing_transaction_idstring

決済後の請求トランザクションID。タスクIDとは別個のものです。

statusstring

タスクのステータス: pending(保留中)、processing(処理中)、completed(完了)、failed(失敗)。

progressinteger

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

video_urlstring

生成された動画のURL(完了時)。これは30日間有効な TokenLab メディア結果URLです。結果のダウンロード を参照してください。失敗したタスクや未完了のタスクには動画URLは含まれません。

last_frame_urlstring

return_last_frame を指定し、モデルがサポートしている場合に生成される最後のフレームのURL。

videoobject

利用可能な場合に url、duration、width、height を含む単一の動画結果。

videosarray

タスクが複数の出力を返す場合の複数の動画結果。

errorstring | object

タスクが失敗した理由(status が failed の場合のみ)。文字列、または message を含むオブジェクト。既知の場合は type、code、param、retryable も含まれます。失敗したタスクには error_details が含まれる場合もあります。非同期ジョブとポーリング を参照してください。

media_retentionobject

動画の保存ステータス: days および items。各アイテムには url、kind、status、expires_at が含まれます。ステータスが適時に判明しない場合は欠落する可能性がありますが、URLは引き続き機能します。

createdinteger

作成タイムスタンプ。

updatedinteger

最終更新タイムスタンプ。

modelstring

タスクに使用されたモデル。

リクエスト

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

レスポンス

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000,
  "updated": 1706000000
}

結果のダウンロード

video_url は https://api.tokenlab.sh/v1/media-results/{id}.mp4?token=… のような形式です。URL内のトークンが認証情報となるため、Authorization ヘッダーは不要です。このURLは動画を閲覧できる人にのみ共有してください。URLはファイルへリダイレクトされるため、ダウンロード時にはリダイレクトを追跡してください(curl -L)。

  • 結果が最初に記録されてから30日間有効です。それ以上保持する必要がある場合はファイルをダウンロードしてください。データ保持 を参照してください。
  • 404 media_not_found: トークンまたはファイル拡張子が結果と一致しません。受け取ったURLをそのまま使用してください。
  • 410 media_expired: 30日間の期間が終了しています。
  • 502 または 503 media_unavailable: 結果がまだ記録中であるか、TokenLab が混雑しています。Retry-After の遅延後に再試行してください。
  • URLに metadata=true を追加すると、ファイルではなく保存ステータスを読み取ることができます。

一部の結果は https://api.tokenlab.sh/v1/videos/generations/{id}/content として配信されます。このURLにはポーリング時と同じ Authorization: Bearer ヘッダーが必要であり、タスクを所有するワークスペースのみがアクセス可能です。

チェック間隔

  • 5〜10秒ごとにチェックしてください。
  • 長時間実行されるタスクの場合は間隔を長くしてください。
  • アプリケーションの最大待機時間を設定してください。
  • ステータスが failed になった場合は停止し、返された error を表示してください。
import requests
import time

def wait_for_video(task_id, max_wait=600, interval=5):
    """タイムアウト付きで動画を待機します。"""
    start = time.time()

    while time.time() - start < max_wait:
        response = requests.get(
            f"https://api.tokenlab.sh/v1/tasks/{task_id}",
            headers={"Authorization": "Bearer sk-your-api-key"}
        )
        response.raise_for_status()
        data = response.json()

        if data["status"] == "completed":
            return data["video_url"]
        elif data["status"] == "failed":
            raise Exception(data.get("error", "Video generation failed"))

        time.sleep(interval)

    raise TimeoutError("Video generation timed out")

認証

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