媒体指南

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。

API 参考

主题参考
创建 World创建 World
获取任务状态获取任务状态
获取 World 状态(兼容)获取 World 状态
准备素材上传准备素材上传
获取素材获取素材
列出 Worlds列出 Worlds
获取 World获取 World
删除 World删除 World
异步任务异步任务
3D 生成指南3D 生成指南

本页内容