Worlds
创建 World
使用文字、图片或视频创建可探索的 3D World
创建可探索的 3D World。响应会返回任务 ID。用任务 id 调用 GET /v1/tasks/{id} 查询进度和结果。
通过 Models API 选择当前可用的 Marble 模型。
请求体
marble-1.0通过 Models API 选择当前可用的 Marble 模型。
用于纯文本生成的文本提示词,也可作为图片或视频输入的引导。最多 4000 个字符。world_prompt、prompt、image、image_url、images、video_url 至少要传一个。
World Labs 原生 world_prompt 对象,面向高级用法,支持 text、image、multi-image 和 video。内容引用可以指向用准备 World 素材上传上传的文件:{ "source": "media_asset", "media_asset_id": "..." }。
Base64 或 data URL 图片提示。
图片 URL 提示。
用于快捷多图生成的多个图片提示。最多提供 4 张图片,每张可以是 URL、Base64 或 data URL 字符串,也可以是带 uri、image_url 或 url(以及可选 azimuth 数字)的对象。若使用原生 World Labs 重建模式,请传入 world_prompt.type="multi-image"、reconstruct_images: true,并最多提供 8 张图片。
视频 URL 提示。
对于图片输入,设置为 true 表示已有全景图,false 表示普通单图,或使用 auto。
可选随机种子,范围为 0 到 4294967295。
可选的生成世界显示名称,最多 64 个字符。
可选的 World Labs 标签。最多提供 10 个标签,每个标签最多 32 个字符。
可选的可见性和访问设置:public、allow_id_access、allowed_readers 和 allowed_writers。public: true 请求创建公开可见的 World。
响应
TokenLab 任务 ID。用它调用 GET /v1/tasks/{id} 查询。
同一个任务 ID 的兼容字段名。
World Labs 操作 ID。
World 状态地址,位于 /v1/worlds/generations/{id}。这是兼容端点,请改用 id 调用 GET /v1/tasks/{id}。
任务状态:pending、processing、completed 或 failed。
生成完成后返回的 Marble 世界 URL。
可用时返回的碰撞网格 GLB URL。
可用时返回的全景图 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 API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
请求头
单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。
可选值
- "auto"
- "verified"
- "official"
可选键,用于确保创建请求可安全重试。请为每个任务发送一个新的唯一值(如 UUID)。使用相同键和相同请求体的重试将返回原始创建请求的结果(通常是原始任务),而不会创建、分发或扣除第二个任务。若使用已接受的键但请求体不同,则会返回 409 错误。超过 255 个字符的键将被忽略,此时该请求不具备幂等性保护。请参阅 安全地使用幂等键进行重试。
1 <= length <= 255请求体
application/json
响应
application/json
application/json
application/json
application/json
application/json