> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# World を作成

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

World Labs Marble で探索可能な 3D ワールドを生成します。この API は非同期です。作成レスポンスにはタスク識別子と、ステータス確認用の `poll_url` が返ります。

対応モデルは `marble-1.0`、`marble-1.1`、`marble-1.1-plus` です。World Labs のドキュメントには `marble-1.0-draft` も記載されていますが、TokenLab は現時点でこのエンドポイントでは draft 生成を公開していません。

## リクエストボディ

<ParamField body="model" type="string" default="marble-1.0">
  使用する Marble モデル：`marble-1.0`、`marble-1.1`、`marble-1.1-plus`。
</ParamField>

<ParamField body="prompt" type="string">
  テキストのみの生成、または画像・動画入力時のガイダンスとして使うテキストプロンプトです。
</ParamField>

<ParamField body="world_prompt" type="object">
  高度な呼び出し向けの World Labs ネイティブ `world_prompt` オブジェクトです。対応タイプは `text`、`image`、`multi-image`、`video` です。
</ParamField>

<ParamField body="image" type="string">
  Base64 または data URL の画像プロンプトです。
</ParamField>

<ParamField body="image_url" type="string">
  画像 URL プロンプトです。
</ParamField>

<ParamField body="images" type="array">
  簡易 multi-image 生成用の複数画像プロンプトです。最大 4 枚まで指定できます。World Labs ネイティブの再構成モードでは、`world_prompt.type="multi-image"` と `reconstruct_images: true` を指定し、最大 8 枚まで渡せます。
</ParamField>

<ParamField body="video_url" type="string">
  動画 URL プロンプトです。
</ParamField>

<ParamField body="is_pano" type="boolean | string">
  画像入力では、既存のパノラマなら `true`、通常の単一画像なら `false`、または `auto` を指定します。
</ParamField>

<ParamField body="seed" type="integer">
  任意のシード値です。0 から 4294967295 まで指定できます。
</ParamField>

<ParamField body="display_name" type="string">
  生成されるワールドの任意の表示名です。最大 64 文字です。
</ParamField>

<ParamField body="tags" type="array">
  任意の World Labs タグです。最大 10 個、各タグ最大 32 文字です。
</ParamField>

<ParamField body="permission" type="object">
  任意の World Labs permission オブジェクトです。
</ParamField>

## レスポンス

<ResponseField name="id" type="string">
  ポーリング用の公開タスク ID です。
</ResponseField>

<ResponseField name="task_id" type="string">
  非同期タスク識別子の別名です。
</ResponseField>

<ResponseField name="operation_id" type="string">
  World Labs のオペレーション ID です。
</ResponseField>

<ResponseField name="poll_url" type="string">
  このタスクに推奨されるポーリング URL です。
</ResponseField>

<ResponseField name="status" type="string">
  タスク状態：`pending`、`processing`、`completed`、`failed`。
</ResponseField>

<ResponseField name="world_marble_url" type="string">
  完了時の生成済み Marble ワールド URL です。
</ResponseField>

<ResponseField name="glb_url" type="string">
  利用可能な場合のコライダーメッシュ GLB URL です。
</ResponseField>

<ResponseField name="pano_url" type="string">
  利用可能な場合のパノラマ画像 URL です。
</ResponseField>

## 料金

World Labs は credits で課金します。TokenLab はリクエスト種別の最大値を事前控除し、完了した operation から `cost.total_credits` が得られる場合は実 credits で精算します。標準 Marble リクエストは最大 1,600 credits、`marble-1.1-plus` は最大 3,100 credits です。

## スコープ

これらの管理エンドポイントは TokenLab 所有のメディアアセットと完了済み world を対象にします。`marble-1.0-draft` 生成および単独の pano/depth ツールはまだ公開していません。

<RequestExample>
  ```bash cURL theme={null}
  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": "夕暮れの静かな海辺の町、細い路地と温かな灯り"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.tokenlab.sh/v1/worlds/generations",
      headers={"Authorization": "Bearer sk-your-api-key"},
      json={
          "model": "marble-1.1",
          "prompt": "夕暮れの静かな海辺の町、細い路地と温かな灯り",
      },
  )

  task = response.json()
  print(task["id"], task["poll_url"])
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.tokenlab.sh/v1/worlds/generations', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk-your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'marble-1.1',
      prompt: '夕暮れの静かな海辺の町、細い路地と温かな灯り'
    })
  });

  const task = await response.json();
  console.log(task.id, task.poll_url);
  ```
</RequestExample>