Worlds

ワールドの作成

World Labs Marbleワールド生成タスクを作成します

POST
/v1/worlds/generations

World Labs Marbleを使用して探索可能な3Dワールドを生成します。これは非同期APIです。作成レスポンスはタスクIDを返します。ステータスを確認するには、タスクの id を使用して GET /v1/tasks/{id} をポーリングしてください。

Models API を使用して、現在利用可能なMarbleモデルを選択します。

リクエストボディ

modelstringデフォルト: marble-1.0

Models API を使用して、現在利用可能なMarbleモデルを選択します。

promptstring

テキストのみの生成用のテキストプロンプト、または画像および動画入力用のガイダンス。最大4000文字。world_prompt、prompt、image、image_url、images、または video_url のうち少なくとも1つを送信してください。

world_promptobject

高度な呼び出し元向けのネイティブWorld Labs world_prompt オブジェクト。サポートされているプロンプトタイプは text、image、multi-image、video です。コンテンツ参照は、メディアアセットアップロードの準備 でアップロードしたファイルを指定できます: { "source": "media_asset", "media_asset_id": "..." }。

imagestring

Base64またはデータURL画像プロンプト。

image_urlstring

画像URLプロンプト。

imagesarray

ショートカットによるマルチ画像生成用の複数画像プロンプト。最大4つの画像(それぞれURL、Base64またはデータURL文字列、あるいは uri、image_url、または url と任意の azimuth 数値を持つオブジェクト)を指定します。ネイティブWorld Labs再構成モードの場合は、world_prompt.type="multi-image" を渡し、reconstruct_images: true および最大8つの画像を指定します。

video_urlstring

動画URLプロンプト。

is_panoboolean | string

画像入力の場合、既存のパノラマには true、通常の単一画像には false、または auto を設定します。

seedinteger

0から4294967295までの任意のシード値。

display_namestring

生成されたワールドの任意の表示名。最大64文字。

tagsarray

任意のWorld Labsタグ。最大10個のタグ(各タグ最大32文字)を指定します。

permissionobject

任意の公開設定およびアクセス設定: public、allow_id_access、allowed_readers、および allowed_writers。public: true はワールドを一般公開するようリクエストします。

レスポンス

idstring

公開タスクID。これを使用して GET /v1/tasks/{id} をポーリングします。

task_idstring

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

operation_idstring

World LabsオペレーションID。

poll_urlstring

/v1/worlds/generations/{id} 配下のワールドステータスURL。これは互換性のためのエンドポイントです。代わりに id を使用して GET /v1/tasks/{id} をポーリングしてください。

statusstring

タスクステータス: pending、processing、completed、または failed。

world_marble_urlstring

完了時に生成されるMarbleワールドのURL。

glb_urlstring

利用可能な場合のコライダーメッシュGLB URL。

pano_urlstring

利用可能な場合のパノラマ画像URL。

料金

現在の料金については Pricing API を参照してください。最終的な請求金額は使用履歴に表示されます。

エラー

  • 400 invalid_request: プロンプト入力が送信されなかったか、フィールドが範囲外です。param に該当するフィールド名が示されます。
  • 400 model_not_found または unsupported_endpoint: モデルが呼び出し可能なMarbleモデルではありません。
  • 403 media_asset_not_owned または 404 media_asset_not_found: world_prompt 内の media_asset_id が別のWorkspaceに属しているか、存在しません。
  • 402: 残高不足のためタスクを開始できません。

リクエスト

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"
  }'
{  "id": "string",  "task_id": "string",  "operation_id": "string",  "status": "pending",  "poll_url": "string",  "world_id": "string",  "world_marble_url": "string",  "model_url": "string",  "glb_url": "string",  "pano_url": "string",  "thumbnail_url": "string",  "caption": "string",  "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"    }  }}

認証

BearerAuth
AuthorizationBearer <token>

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

場所: header

ヘッダー

X-TokenLab-Delivery-Policy?string

リクエストごとの配信ポリシー。APIキーおよびWorkspaceのデフォルト設定を上書きします。自動的にまず TokenLab Verified を試行し、出力、リクエストの受け入れ、または永続的なリソース作成の前に、一度だけ Official に切り替える場合があります。

指定できる値

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

作成リクエストを安全に再試行するためのオプションのキー。タスクごとに新しい一意の値(UUIDなど)を送信してください。同じキーとボディで再試行すると、元の作成リクエストの結果(通常は元のタスク)が返され、2つ目のタスクの作成、ディスパッチ、課金は行われません。すでに受け入れられたキーで異なるボディを指定すると、409で拒否されます。255文字を超えるキーは無視され、そのリクエストには冪等性保護が適用されません。詳細は冪等性キーを使用した安全な再試行を参照してください。

長さ1 <= length <= 255

リクエストボディ

application/json

レスポンス

application/json

application/json

application/json

application/json

application/json