开发者 API | Open3DAI

快速开始

创建 API 密钥

登录后进入「账户 → API 密钥 → 创建」。请立即复制明文密钥，它只会显示一次。

发出第一个请求

用文字生成一个 3D 模型：

curl -X POST https://open3dai.com/api/v1/generations/text-to-3d \
  -H "Authorization: Bearer trf_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "text_to_3d",
    "prompt": "A medieval sword with a golden hilt",
    "style": "realistic",
    "mode": "quality",
    "webhookUrl": "https://yourapp.com/hooks/open3dai"
  }'

# 201 Created
{
  "ok": true,
  "data": {
    "taskId": "gen_abc123",
    "provider": "procedural",
    "status": "processing",
    "creditsUsed": 20,
    "creditsRemaining": 980
  },
  "requestId": "req_1a2b3c4d"
}

轮询或等待回调

用 GET /generations/{taskId} 查询状态。当 status 为 completed 时，data.outputModelUrl 指向生成的 .glb 文件。

curl https://open3dai.com/api/v1/generations/gen_abc123 \
  -H "Authorization: Bearer trf_live_xxx"

响应信封

所有响应遵循同一个信封结构，并且每个响应都带 X-Request-ID 头——反馈问题时请附上它。

// 成功 (2xx)
{ "ok": true, "data": { … }, "requestId": "req_abc123" }

// 失败 (4xx / 5xx)
{
  "ok": false,
  "error": {
    "code": "snake_case_code",
    "message": "Human-readable message.",
    "requestId": "req_abc123",
    "details": { }
  }
}

接口列表

Method	Path	作用域	说明
`POST`	`/generations/text-to-3d`	`write`	用自然语言提示词生成 3D 模型。
`POST`	`/generations/image-to-3d`	`write`	把单张参考图（JPG/PNG/WEBP，base64 data URL）转成带贴图的 3D 模型。
`POST`	`/generations/multiview-to-3d`	`write`	用至少 2 张不同角度的照片重建 3D 模型。
`GET`	`/generations/{taskId}`	`read`	查询任务状态、产物地址与积分消耗。
`GET`	`/generations/{taskId}/model`	`read`	直接下载生成的模型文件。
`GET`	`/usage`	`read`	查询积分余额与限流配额（不消耗积分）。
`GET`	`/api/docs`	—	交互式 OpenAPI 文档。

幂等性

网络重试很常见。没有幂等机制时，一次重试可能创建重复任务并重复扣费。

-H "Idempotency-Key: 8f14e45f-ceea-467a-9a1e-3b1c2d4e5f60"

格式：1–255 个字符，允许 A–Z a–z 0–9 _ -。建议每个客户端动作使用一个随机 UUID v4。
同一个键重复提交且请求体一致 → 直接回放首次响应，不重复扣费。
同一个键但请求体不同 → 400 validation_failed。
格式非法 → 400 invalid_idempotency_key。

Webhook

在创建任务时传入 webhookUrl，任务结束（成功或失败）后我们会向它 POST 结果。

POST {your webhookUrl}
X-open3dai-Event: generation.completed   # or generation.failed
X-open3dai-Delivery: gen_abc123

{
  "taskId": "gen_abc123",
  "status": "completed",
  "outputModelUrl": "https://open3dai.com/api/v1/generations/gen_abc123/model",
  "thumbnailUrl": "https://open3dai.com/api/v1/generations/gen_abc123/thumbnail",
  "creditsUsed": 20,
  "errorCode": null,
  "timestamp": "2026-08-14T14:00:00Z"
}

投递保证。失败（非 2xx 或网络错误）最多重试 3 次，间隔 1s / 5s / 15s。除 429 外的 4xx 视为永久失败、不再重试。请求 10 秒超时，请让处理逻辑保持轻量并尽快返回 2xx。

速率限制

每个 API 密钥 600 请求/小时，使用滚动窗口。

Header	含义
`X-RateLimit-Limit`	窗口内的最大请求数（600）。
`X-RateLimit-Remaining`	当前窗口剩余请求数。
`Retry-After`	仅 429 返回：距离窗口重置的秒数。
`X-Request-ID`	每个请求的唯一标识，便于排查。

错误码

Code	HTTP	触发条件
`missing_bearer_token`	401	缺少 Authorization: Bearer … 请求头。
`invalid_api_key`	401	密钥格式错误、已撤销或不存在。
`insufficient_scope`	403	密钥缺少该接口所需的作用域。
`insufficient_credits`	402	账户余额不足以完成本次生成。
`validation_failed`	400	请求体未通过校验，详见 details.issues。
`invalid_idempotency_key`	400	Idempotency-Key 格式不合法。
`invalid_request_body`	400	请求体不是合法 JSON。
`rate_limit_exceeded`	429	小时配额耗尽，见 Retry-After。
`task_not_found`	404	任务不存在或不属于本账号。
`internal_error`	500	服务器内部错误，请带 requestId 反馈。

校验问题码

prompt_required — 文字转 3D 缺少提示词。
prompt_too_long — 提示词超过 2000 字符。
image_required — 缺少 imageDataUrl。
invalid_image_format — 不是受支持的 base64 data URL。
image_too_large — 解码后超过 20MB。
multiview_requires_two_images — 多视图少于 2 张图片。
invalid_mode — mode 必须是 speed 或 quality。
invalid_style — style 取值不被识别。
idempotency_key_reused — 同一个幂等键配了不同的请求体。

创建 API 密钥

登录后进入「账户 → API 密钥 → 创建」。请立即复制明文密钥，它只会显示一次。

账户开发者 API → OpenAPI