94 lines
2.0 KiB
Markdown
94 lines
2.0 KiB
Markdown
# 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>`。
|