> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aisonar.dev/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`，但 AI Sonar 目前尚未在此端点开放 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">
  用于快捷多图生成的多个图片提示。最多提供 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 权限对象。
</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 计费。AI Sonar 会先按请求类型的最大值预扣，并在完成的 operation 返回 `cost.total_credits` 时按实际 credits 结算。标准 Marble 请求最多 1,600 credits。`marble-1.1-plus` 请求最多 3,100 credits。

## 范围

这些管理端点覆盖 AI Sonar 归属的媒体资产和已完成生成的 worlds。AI Sonar 仍不开放 `marble-1.0-draft` 生成或独立 pano/depth 工具。

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.aisonar.dev/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.aisonar.dev/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.aisonar.dev/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>