ビデオと素材
動画ステータスの取得
動画タスクのステータスと結果を取得します
GET /v1/videos/generations/{id} は互換性維持のためのエンドポイントです。既存のインテグレーション向けに引き続きサポートされており、GET /v1/tasks/{id} と同じ形式で結果を返します。新規のインテグレーションでは GET /v1/tasks/{id} をポーリングしてください。詳細は タスクステータスの取得 を参照してください。
パスパラメータ
動画作成リクエストによって返されたタスクIDです。id と task_id は同一のタスクを指します。
タスクが失敗した場合でも、ステータスの読み取りは HTTP 200 を返します。status を確認してください。期限切れまたは利用不可能なタスクは 404 async_task_not_found を返します。自身のワークスペースに属さないタスクは 403 task_not_owned を返します。503 async_task_owner_unavailable は一時的なエラーです。リクエストを再試行してください。
レスポンス
結果、エラー、タイムスタンプ、モデルを記述するフィールドは、タスクで利用可能な場合に返されます。
タスクID。
id と同じタスクID。
このタスクのステータスURL。id を使用して GET /v1/tasks/{id} をポーリングしてください。
決済後の請求トランザクションID。タスクIDとは別個のものです。
タスクのステータス: pending(保留中)、processing(処理中)、completed(完了)、failed(失敗)。
0から100までのオプションの進捗率。実際の進捗値が利用可能な場合にのみ返されます。完了の判定には status を使用してください。
生成された動画のURL(完了時)。これは30日間有効な TokenLab メディア結果URLです。結果のダウンロード を参照してください。失敗したタスクや未完了のタスクには動画URLは含まれません。
return_last_frame を指定し、モデルがサポートしている場合に生成される最後のフレームのURL。
利用可能な場合に url、duration、width、height を含む単一の動画結果。
タスクが複数の出力を返す場合の複数の動画結果。
タスクが失敗した理由(status が failed の場合のみ)。文字列、または message を含むオブジェクト。既知の場合は type、code、param、retryable も含まれます。失敗したタスクには error_details が含まれる場合もあります。非同期ジョブとポーリング を参照してください。
動画の保存ステータス: days および items。各アイテムには url、kind、status、expires_at が含まれます。ステータスが適時に判明しない場合は欠落する可能性がありますが、URLは引き続き機能します。
作成タイムスタンプ。
最終更新タイムスタンプ。
タスクに使用されたモデル。
リクエスト
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 APIキー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。
場所: header
パスパラメータ
id / task_id によって返される、または poll_url に埋め込まれた非同期タスクID
レスポンス
application/json
application/json
application/json
application/json
application/json
application/json
application/json