# Developer Center · 3DGS 建模 API · 接入简报

你在帮用户接入这个 API。请严格按本简报操作，不要猜测未写明的参数。

## 这是什么
- 上传视频或图片，返回 3DGS（Gaussian Splatting）模型，GLB 等格式下载。
- REST + JSON，无官方 SDK，fetch/curl 即可。所有响应包裹在 {"data": …} 里。
- 计费单位 Points：1 CNY = 10 Points。当前单次建模任务 120.00 pts（12 元）。
  下单前先调估价接口确认，不要替用户假设价格。

## 环境
- Base URL: https://developer.yuanqee.cn
- 认证：X-API-Key: <api_key_id>.<secret>
- 创建类请求（上传 / 完成会话 / 创建任务）必须带 Idempotency-Key 头；
  重试必须复用同一个值，否则可能重复扣费。

## 用户必须自己做（你代办不了，引导用户去网页完成）
1. 打开 https://developer.yuanqee.cn，用手机号验证码登录（首次自动注册）
2. 在「API Keys」页创建 API Key，把 Secret 存进服务端环境变量 DC_API_KEY
3. 在「用量与账单」页充值（微信扫码，0.10 元起，10 Points / 元）
- 控制台的余额 / 账单 / 充值接口走浏览器会话（DC_SESSION），不开放 X-API-Key；
  用户可用「复制我的账户状态」按钮把账户数据交给你。

## 完整流程（你可以代办）
前置：export DC_BASE=https://developer.yuanqee.cn DC_API_KEY=<用户给你>

1. 创建上传会话（size_bytes 为文件字节数，时长单位秒）：
   curl -X POST "$DC_BASE/api/v1/uploads" -H "X-API-Key: $DC_API_KEY" \
     -H "Idempotency-Key: up-001" \
     -d '{"client_file_id":"cap-001","file_name":"capture.mp4","size_bytes":123456,"content_type":"video/mp4","declared_duration_seconds":12.4}'
   → 取 data.upload_session.id、files[0].id、files[0].object.{bucket,key,upload_mode}

2. 取临时 STS 凭证（视频直传对象存储，不经过本服务）：
   curl -X POST "$DC_BASE/api/v1/uploads/$UPLOAD_ID/credentials" -H "X-API-Key: $DC_API_KEY"
   → data.credentials.{endpoint,region,access_key_id,secret_access_key,session_token}

3. 用 S3 兼容 SDK 把文件字节 PutObject 到第 1 步的 bucket/key。
   分片模式上传每个 part 并记录 part_number + etag。

4. 完成文件（单段模式 parts 传空数组）：
   curl -X POST "$DC_BASE/api/v1/uploads/$UPLOAD_ID/files/$FILE_ID/complete" \
     -H "X-API-Key: $DC_API_KEY" -H "Idempotency-Key: done-001" -d '{"parts":[]}'

5. 完成会话，取得 asset_id：
   curl -X POST "$DC_BASE/api/v1/uploads/$UPLOAD_ID/complete" \
     -H "X-API-Key: $DC_API_KEY" -H "Idempotency-Key: fin-001"
   → data.asset_id

6. 估价（推荐；返回本次任务的 points_amount 与价格版本）：
   curl -X POST "$DC_BASE/api/v1/3dgs/estimates" -H "X-API-Key: $DC_API_KEY" \
     -d '{"asset_id":"…"}'

7. 创建任务（会立即扣费；同键重试不会重复扣）：
   curl -X POST "$DC_BASE/api/v1/3dgs/tasks" -H "X-API-Key: $DC_API_KEY" \
     -H "Idempotency-Key: task-001" -d '{"asset_id":"…"}'
   → data.task_id

8. 轮询（每 5–10 秒一次，直到 status 为 succeeded 或 failed）：
   curl "$DC_BASE/api/v1/3dgs/tasks/$TASK_ID" -H "X-API-Key: $DC_API_KEY"

9. 下载（URL 短时有效，拿到后立即下载）：
   curl "$DC_BASE/api/v1/3dgs/tasks/$TASK_ID/download?format=glb" -H "X-API-Key: $DC_API_KEY"

## 出错怎么办
错误为顶层 JSON：{"code","message","request_id","retryable"}（request_id 可直接进工单）。
- 401 Key 无效或已撤销 → 让用户去「API Keys」页检查，不要重试
- 402 余额不足 → 让用户充值，不要重试
- 409 幂等键冲突 → 同键不同参数；换新键前先跟用户确认意图
- 429 限流 → 指数退避后重试
- 5xx → retryable=true 才重试；重试必须复用同一个 Idempotency-Key
- 任务 failed → 响应含失败分类；失败任务按规则自动退款，不要手动补救

## 红线
- API Key 只放服务端环境变量，不进前端代码、不进仓库、不进日志
- 不要替用户创建充值订单（金额必须用户自己确认）
- 视频字节直传对象存储，不要发给 $DC_BASE
