# 3D 世界生成 API 调用规范

当前 3D 世界生成通过智枢外部任务接口调用 World Labs 能力。Base URL 只填写根地址：

```text
https://api.vip98k.com
```

不要填写 `/v1`，也不要填写旧的 `/marble/v1`。

## 鉴权方式

所有请求都必须携带本站发出的智枢 API Key：

```http
Authorization: Bearer <API_KEY>
Accept: application/json
Content-Type: application/json
```

不要使用管理员 Key、其他平台 Key，也不要使用旧的 `WLT-Api-Key` 作为主链路鉴权。

## 模型目录

正式创建任务前，可以先确认这把 Key 是否开通空间生成分组：

```bash
curl "https://api.vip98k.com/api/external/task/models" \
  -H "Authorization: Bearer <API_KEY>"
```

返回内容里应能找到：

```json
{
  "modelId": "world-generation"
}
```

如果找不到，说明这把 Key 没有勾选空间生成分组。

## 创建任务

```bash
curl "https://api.vip98k.com/api/external/task/generate" \
  -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "world-generation",
    "displayName": "Test scene",
    "prompt": "A quiet sunlit courtyard with a small stone fountain."
  }'
```

正常会先返回 `accepted` 或 `running`，这不是失败：

```json
{
  "data": {
    "taskId": "任务ID",
    "status": "accepted",
    "done": false,
    "resultPath": "/api/external/task/result?taskId=任务ID"
  }
}
```

## 查询结果

```bash
curl "https://api.vip98k.com/api/external/task/result?taskId=<任务ID>" \
  -H "Authorization: Bearer <API_KEY>"
```

建议每隔 5 到 10 秒查询一次，最长等待 10 分钟。直到返回：

```json
{
  "data": {
    "status": "succeeded",
    "done": true
  }
}
```

## 常见错误

- 不能用 `/v1/chat/completions`。
- 不能把模型写成 `marble-1.1`。
- 不能把 `accepted` 或 `running` 当作调用失败。
- 不能只等待几十秒就判定超时。
- 必须携带 `Authorization: Bearer <API_KEY>`。