Worlds

创建 World

使用文字、图片或视频创建可探索的 3D World

POST
/v1/worlds/generations

创建可探索的 3D World。响应会返回任务 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 至少要传一个。

world_promptobject

World Labs 原生 world_prompt 对象,面向高级用法,支持 text、image、multi-image 和 video。内容引用可以指向用准备 World 素材上传上传的文件:{ "source": "media_asset", "media_asset_id": "..." }。

imagestring

Base64 或 data URL 图片提示。

image_urlstring

图片 URL 提示。

imagesarray

用于快捷多图生成的多个图片提示。最多提供 4 张图片,每张可以是 URL、Base64 或 data 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 请求创建公开可见的 World。

响应

idstring

TokenLab 任务 ID。用它调用 GET /v1/tasks/{id} 查询。

task_idstring

同一个任务 ID 的兼容字段名。

operation_idstring

World Labs 操作 ID。

poll_urlstring

World 状态地址,位于 /v1/worlds/generations/{id}。这是兼容端点,请改用 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 属于其他工作区,或不存在。
  • 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": "夕阳下安静的海边小镇,有狭窄小巷和温暖灯光"
  }'
{  "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 Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。

可选值

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

可选键,用于确保创建请求可安全重试。请为每个任务发送一个新的唯一值(如 UUID)。使用相同键和相同请求体的重试将返回原始创建请求的结果(通常是原始任务),而不会创建、分发或扣除第二个任务。若使用已接受的键但请求体不同,则会返回 409 错误。超过 255 个字符的键将被忽略,此时该请求不具备幂等性保护。请参阅 安全地使用幂等键进行重试。

长度1 <= length <= 255

请求体

application/json

响应

application/json

application/json

application/json

application/json

application/json