ai-chatbot/docs/worldlabs-proxy-provider-requirements.md

World Labs 3D 世界生成中转接口兼容要求

本文档用于说明我方系统接入 World Labs 3D 世界生成功能时，对第三方中转服务的接口兼容要求。

核心原则

我方系统会按照 World Labs 官方 API 协议发起请求：

{baseUrl} + /marble/v1/...

中转服务需要兼容官方路径、请求体、响应体和错误格式。请不要要求我方把 baseUrl 配置成某个完整接口地址。

正确示例：

http://your-proxy-domain.com

错误示例：

http://your-proxy-domain.com/marble/v1/worlds:generate

我方请求方式

我方后台会在请求中携带：

WLT-Api-Key: {配置的 API Key}
Accept: application/json
Content-Type: application/json

中转服务应支持 WLT-Api-Key 请求头。如果中转服务内部自行管理官方 Key，也可以将该字段作为租户标识或鉴权凭据，但不应要求我方改成其他 header。

必须兼容的接口

1. 准备上传素材

POST {baseUrl}/marble/v1/media-assets:prepare_upload

请求体示例：

{
  "file_name": "input.jpg",
  "extension": "jpg",
  "kind": "image",
  "metadata": {
    "mime_type": "image/jpeg",
    "uploaded_from": "canvas_world_mode"
  }
}

响应必须包含可用的上传信息：

{
  "media_asset": {},
  "upload_info": {
    "upload_url": "https://...",
    "upload_method": "PUT",
    "required_headers": {}
  }
}

要求：

• upload_url 必须可由我方服务器直接访问。
• upload_method 如为 PUT，必须支持 PUT 上传文件二进制。
• required_headers 中返回的 header，我方会原样带上。
• 上传成功时，上传地址必须返回 2xx。

2. 创建世界生成任务

POST {baseUrl}/marble/v1/worlds:generate

请求体示例：

{
  "display_name": "",
  "model": "marble-1.1",
  "permission": {
    "public": false
  },
  "world_prompt": {
    "type": "image",
    "image_prompt": {
      "source": "media_asset",
      "media_asset_id": "media_asset_id_here"
    }
  }
}

响应需兼容官方 operation 结构，至少包含：

{
  "operation_id": "task-id",
  "done": false,
  "metadata": {
    "progress": {
      "status": "RUNNING"
    }
  }
}

要求：

• operation_id 必须稳定，后续查询状态必须使用同一个 id。
• 不要在创建成功但任务未完成时返回业务失败。
• 如果余额不足、Key 无效，应返回明确 HTTP 状态码和错误信息。

3. 查询任务状态

GET {baseUrl}/marble/v1/operations/{operation_id}

运行中响应示例：

{
  "operation_id": "task-id",
  "done": false,
  "metadata": {
    "progress": {
      "status": "RUNNING",
      "description": "World generation in progress"
    }
  }
}

成功响应示例：

{
  "operation_id": "task-id",
  "done": true,
  "error": null,
  "metadata": {
    "progress": {
      "status": "SUCCEEDED"
    },
    "world_id": "world-id"
  },
  "response": {
    "world_id": "world-id",
    "world_marble_url": "https://marble.worldlabs.ai/world/...",
    "assets": {
      "mesh": {
        "collider_mesh_url": "https://cdn.marble.worldlabs.ai/.../model.glb"
      },
      "imagery": {
        "pano_url": "https://cdn.marble.worldlabs.ai/.../rgb_0.png"
      },
      "thumbnail_url": "https://cdn.marble.worldlabs.ai/.../thumbnail.webp",
      "splats": {
        "spz_urls": {
          "100k": "https://cdn.marble.worldlabs.ai/...100k.spz",
          "150k": "https://cdn.marble.worldlabs.ai/...150k.spz",
          "500k": "https://cdn.marble.worldlabs.ai/...500k.spz",
          "full_res": "https://cdn.marble.worldlabs.ai/...full.spz"
        }
      }
    }
  }
}

失败响应示例：

{
  "operation_id": "task-id",
  "done": true,
  "error": {
    "message": "Insufficient account balance"
  }
}

要求：

• done=false 表示任务仍在运行。
• done=true 且 error=null 表示任务成功。
• done=true 且 error.message 存在表示任务失败。
• 不要把运行中的任务返回为 HTTP 404。
• 不要因为任务未完成就返回 Operation not found。

4. 查询世界详情

GET {baseUrl}/marble/v1/worlds/{world_id}

当 operations 成功响应中资产不完整时，我方会调用该接口补充详情。响应应包含与 response 内 world 对象兼容的数据结构。

错误码要求

建议按以下语义返回：

场景	HTTP 状态码	message 示例
API Key 缺失或无效	401	Unauthorized
权限不足	403	Forbidden
余额不足	402 或 403	Insufficient account balance
请求体错误	400	Invalid request body
任务不存在	404	Operation not found
上游超时	504	Upstream timeout
上游异常	502	Upstream error

响应体建议：

{
  "message": "Insufficient account balance"
}

或：

{
  "error": {
    "message": "Insufficient account balance"
  }
}

超时与稳定性要求

• prepare_upload 建议 30 秒内返回。
• worlds:generate 建议 60 秒内返回 operation，而不是等待生成完成。
• operations/{id} 建议 10 秒内返回当前状态。
• 生成任务本身可异步运行，前端会轮询状态。
• 同一个 operation_id 多次查询必须返回同一个任务状态，不应随机切换账号或路由。

上传地址要求

prepare_upload 返回的 upload_url 可以是官方签名地址，也可以是中转服务自己的上传地址，但必须满足：

• 我方服务器可直接访问。
• 支持返回的 upload_method。
• 支持上传原始文件二进制。
• 上传成功返回 2xx。
• 上传完成后，后续 worlds:generate 使用的 media_asset_id 必须可用。

安全要求

• 不要在错误信息中返回完整官方 API Key。
• 日志中建议只记录 Key 前后少量字符，例如 sk-****abcd。
• 中转服务如保存官方 Key，应加密存储。
• 上传 URL 如有签名，应设置合理过期时间。
• 不要允许用户通过 baseUrl 或 path 注入访问内网地址。

我方验收用例

中转服务上线前，请至少通过以下链路：

1. POST /marble/v1/media-assets:prepare_upload 返回 media_asset_id 和可上传 URL。
2. 使用返回的 upload_url 上传图片，返回 2xx。
3. POST /marble/v1/worlds:generate 返回稳定 operation_id。
4. GET /marble/v1/operations/{operation_id} 在运行中返回 done=false。
5. 任务完成后返回 done=true、error=null、world_id 和资产 URL。
6. 资产 URL 中至少应包含 thumbnail、pano、mesh 或 spz 中的一种，最好完整返回。
7. GET /marble/v1/worlds/{world_id} 可返回完整 world 详情。

配置示例

我方系统中的 API 地址应填写中转根地址：

http://23.169.168.133:8080

最终我方会请求：

http://23.169.168.133:8080/marble/v1/media-assets:prepare_upload
http://23.169.168.133:8080/marble/v1/worlds:generate
http://23.169.168.133:8080/marble/v1/operations/{operation_id}
http://23.169.168.133:8080/marble/v1/worlds/{world_id}

如果切回官方接口，配置为：

https://api.worldlabs.ai

最终请求：

https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload
https://api.worldlabs.ai/marble/v1/worlds:generate
https://api.worldlabs.ai/marble/v1/operations/{operation_id}
https://api.worldlabs.ai/marble/v1/worlds/{world_id}

结论

中转服务需要做的是兼容 World Labs 官方 API 协议，而不是要求我方修改接口路径。只要中转根地址完整支持 /marble/v1/...，我方系统就可以在官方接口和中转接口之间无缝切换。