メディアガイド
Worlds
探索可能な Worlds を生成し、メディアプロンプトをアップロードし、タスクを polling して完了済み World を管理します。
World 生成は探索可能な Marble World を非同期で作成します。ユーザーが開いたり再訪できる環境が出力の場合は Worlds を使います。単体のダウンロード可能なモデルアセットが必要な場合は 3D 生成を使います。
入力とメディアアセット
World タスクは、モデルとリクエスト形式に応じて、テキスト、画像、複数画像、動画から開始できます。再利用するメディアプロンプトは先に media asset を準備し、World リクエスト内で参照します。
メディアとワールドの記録へのアクセスは API キーの所属組織で確認されます。共有前にモデルの permission 設定を確認してください。返されたアセットや閲覧 URL には別のアクセス規則がある場合があります。
作成と polling
作成レスポンスには公開タスク ID と通常 poll_url が含まれます。進捗表示の前に ID を保存し、poll_url または GET /v1/tasks/{id} を completed または failed まで確認します。
curl -X POST "https://api.tokenlab.sh/v1/worlds/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "marble-1.1",
"prompt": "A quiet coastal town at sunset with narrow alleys and warm lights"
}'完了済み Worlds の管理
Worlds の list/get は自分のアカウントで利用できる完了済み World 用です。pending または failed の生成タスクは task status endpoint を使います。delete はユーザーが生成 World を削除する意図を示した時だけ使います。
よくある落とし穴
- すべての World モデルがすべての入力タイプを支援するとは限らない。
- 署名付き画像・動画 URL はサービス側取得の再試行に十分な有効期限を持たせる。
- timeout 後に再試行する前に、返された task ID を保存して確認する。
- ダウンロード可能なモデルファイルが必要なら Worlds ではなく 3D 生成を使う。
API リファレンス
| トピック | リファレンス |
|---|---|
| World を作成 | World を作成 |
| World 状態を取得 | World 状態を取得 |
| メディアアセットアップロードを準備 | メディアアセットアップロードを準備 |
| メディアアセットを取得 | メディアアセットを取得 |
| Worlds 一覧 | Worlds 一覧 |
| World を取得 | World を取得 |
| World を削除 | World を削除 |
| 非同期ジョブ | 非同期ジョブ |
| 3D 生成ガイド | 3D 生成ガイド |