媒体指南
Worlds
用文字、图片或视频创建可探索的 Marble 世界
Worlds 可以创建一个供人打开和探索的 Marble 环境。如果需要的是可下载的对象而不是环境,请使用 3D 生成。
可下载的 World 文件(如 splat、网格和全景图)会自动保存 30 天副本,并使用 TokenLab 媒体结果 URL。可交互的 World 页面和 World 记录不在此列。见数据保留。
输入与素材
根据模型不同,World 可以从文字、一张或多张图片,或视频开始。Marble 模型(marble-*)可在 GET /v1/models?recommended_for=3d 中找到,操作类型为 world-generation。至少提供一种输入:
| 输入 | 字段 |
|---|---|
| 文字 | prompt,最长 4,000 个字符 |
| 一张图片 | image_url,或 Base64 / data URL 形式的 image;is_pano 表示它是否已是全景图 |
| 多张图片 | images,最多 4 张 |
| 视频 | video_url |
| 高级用法 | world_prompt,原生提示对象,可引用已上传的素材 |
可选字段有 display_name(最长 64 个字符)、seed、tags(最多 10 个)和 permission。需要重复使用的媒体只需上传一次,之后通过素材 ID 引用。
媒体和世界记录按 API Key 所属组织校验访问权限。分享世界前,请核对所选模型的 permission 选项;返回的素材或查看链接可能有独立的访问规则。
创建并查询状态
创建成功后会返回任务 ID,通常还会提供 poll_url。保存这个 ID,用它调用 GET /v1/tasks/{id} 查询,直到状态变为 completed 或 failed。Worlds 的 poll_url 指向 /v1/worlds/generations/{id},这是兼容路径,请改用 /v1/tasks/{id}。
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 查询任务:
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"管理已完成的 World
用 POST /v1/worlds/list 和 GET /v1/worlds/{id} 查看账户中已完成的 World,用 DELETE /v1/worlds/{id} 删除。仍在生成或已失败的生成任务,请使用 GET /v1/tasks/{id}。只有用户有意从你的产品中移除已生成的 World 时才删除。
常见陷阱
- 不要假设每个 World 模型都支持所有输入类型。
- 带签名的图片或视频 URL 要保持足够长的有效期,确保服务能够读取。
- 超时后重试前,请先保存返回的任务 ID。
- 需要可下载的模型文件时使用 3D 生成,而不是可探索的 World。