# WarmPix 图片转 3D API

## 服务概览

**服务地址：** `https://img3d.warmpix.com`  
**API 版本：** `2.1.0`  
**引擎：** 当前部署的单图 Pixal3D 推理流程  
**输出：** 带材质纹理的 GLB 2.0 网格，不包含自动骨骼绑定。

调用顺序为：**建立会话 → 上传图片 → 轮询任务 → 下载模型**。任务异步执行，上传成功不代表模型已经生成。只有 `state` 等于 `complete` 才能下载 GLB。

本文描述的是 WarmPix 封装的 HTTP API，不是腾讯官方在线服务。字段、默认值和认证方式以本项目 `server.py`、`api_contract.py` 和实际部署为准。

提供 [英文完整示例](/docs/en/)、[可直接运行的 Python 客户端](/docs/img3d_client.py) 和 [OpenAPI 规范](/api/openapi.json)。必须直接使用 HTTPS，不要向 HTTP 重定向入口上传文件。

## 1. 认证：Cookie 与 CSRF

目前没有 API Key、Bearer Token 或账号登录。每个客户端通过 `GET /api/session` 建立私有匿名会话。

| 内容 | 获取方式 | 使用方式 |
| --- | --- | --- |
| `wp3d_session` | `/api/session` 响应中的 `Set-Cookie` | 所有私有任务和文件请求携带此 Cookie |
| CSRF Token | 同一响应 JSON 中的 `csrf` | POST、DELETE 请求通过 `X-CSRF-Token` 发送 |

只复制 CSRF 而不保留对应 Cookie 无法调用。Cookie 带有 Secure、HttpOnly、SameSite=Strict 属性；有效会话请求 `/api/session` 可刷新浏览器的七天有效期。

请持久保存 Cookie 文件，并设置为仅自己可读，绝不能提交到 Git 或发布到网页。删除、丢失或过期后，无法仅凭任务 ID 找回匿名会话。Python/cURL 与另一个浏览器默认不共享任务。

服务器端或命令行请求可以不发送 `Origin`。发送时必须是 `https://img3d.warmpix.com`。本站没有开放任意跨域浏览器调用；其他网站应通过自己的后端对接。不要关闭 TLS 证书验证。

## 2. Python 快速开始

需要 Python 3.10 及以上版本和 `requests`：

```bash
python3 -m pip install requests
curl --fail --show-error \
  https://img3d.warmpix.com/docs/img3d_client.py \
  -o img3d_client.py

python3 img3d_client.py ./object.png \
  --output ./object.glb \
  --session-file ./.warmpix-img3d.cookies \
  --resolution 1024 \
  --texture 4096 \
  --quality detail \
  --seed 42
```

客户端自动建立会话、取得 CSRF、检查引擎、提交带幂等键的任务、轮询真实阶段，并先将 GLB 下载到临时文件。校验 GLB 文件头、声明长度和服务器记录的字节数后，才写入最终文件名，并输出 SHA-256 校验值。已有输出文件不会被覆盖，除非明确使用 `--overwrite`；下载或校验失败时，原文件保持完整。

导出元数据为可选信息。模型已下载并通过校验后，即使元数据缺失或暂时不可用，客户端也会提示警告并正常退出。此时 `--record` 记录中的 `export` 为 null，另有 `metadata_error` 说明原因；生成失败或模型下载失败仍会使命令失败。

打开可见表面的原图颜色投影：

```bash
python3 img3d_client.py ./object.png \
  --output ./object-reference.glb \
  --preserve-reference \
  --record ./generation-result.json
```

记录文件包含任务参数、处理时间、文件校验值和导出元数据，不包含 Cookie 或 CSRF。退出终端后，可以使用原 Cookie 文件与任务 ID 继续等待或下载：

```bash
python3 img3d_client.py \
  --job-id YOUR_JOB_ID \
  --session-file ./.warmpix-img3d.cookies \
  --output ./object.glb \
  --timeout 3600
```

客户端轮询超时不会取消服务器任务。失败任务可明确加 `--retry-failed` 重试，但只有 `--job-id` 指向 `failed` 状态时才会重新排队。若只是网络中断，应先查询原任务，而不是盲目重新生成。

## 3. cURL 提交示例

需要 Bash、cURL 和 `jq`。这是单次提交示例；包含有限轮询、失败处理和 GLB 文件校验的完整脚本见 [英文指南](/docs/en/)。

```bash
umask 077
BASE='https://img3d.warmpix.com'
COOKIE='./.warmpix-img3d.cookies'

SESSION=$(curl --fail-with-body --silent --show-error \
  --cookie "$COOKIE" --cookie-jar "$COOKIE" \
  "$BASE/api/session")
CSRF=$(printf '%s' "$SESSION" | jq -er '.csrf')

curl --fail-with-body --silent --show-error "$BASE/api/health" | jq .
# 确认 ready 为 true 后再提交。
KEY=$(python3 -c 'import uuid; print(uuid.uuid4())')
printf 'Idempotency-Key: %s\n' "$KEY"

curl --fail-with-body --silent --show-error \
  --cookie "$COOKIE" \
  --header "X-CSRF-Token: $CSRF" \
  --header "Idempotency-Key: $KEY" \
  --form 'image=@./object.png' \
  --form 'seed=42' \
  --form 'resolution=1024' \
  --form 'texture=4096' \
  --form 'texture_quality=detail' \
  --form 'preserve_reference=false' \
  "$BASE/api/jobs" | jq .
```

将响应的 `id` 保存为 `JOB_ID`。每三秒调用 `GET /api/jobs/$JOB_ID`。当 `state=complete` 时，携带同一 Cookie 下载：

```bash
curl --fail --show-error --cookie "$COOKIE" \
  "$BASE/api/jobs/$JOB_ID/model" -o object.glb

curl --fail-with-body --silent --show-error --cookie "$COOKIE" \
  "$BASE/api/jobs/$JOB_ID/metadata" | jq .
```

不要手动设置 multipart 的 `Content-Type`，应由 HTTP 库或 cURL 自动生成 boundary。不能用 JSON、base64、图片 URL 或多张图片列表替代 `image` 文件字段。

## 4. 生成参数

`POST /api/jobs` 接收 `multipart/form-data`。

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `image` | 文件 | 必填 | 单张 PNG、JPEG 或 WEBP |
| `seed` | 整数 | `42` | 0 至 2147483647 |
| `resolution` | 整数 | `1024` | 1024 或 1536；几何生成分辨率 |
| `texture` | 整数 | `4096` | 1024、2048 或 4096；纹理图集尺寸 |
| `texture_quality` | 字符串 | `detail` | standard 为 12 步；detail 为 24 步并带轻度颜色清晰度滤镜 |
| `preserve_reference` | 布尔值 | `false` | 开启可见表面的原图颜色投影；发送 true 或 false |

可以从 `1024 / 2048 / standard` 获取较小、较轻的结果；默认是 `1024 / 4096 / detail`。`1536 / 4096 / detail` 请求更高几何精度，但不保证每张图片都会更好，也可能增加显存和时间需求。

原图投影使用对齐后的高分辨率图像、深度遮挡检查、朝向检查和透明度过滤，只有足够可信的可见表面才混入原图 RGB。轮廓重合程度不足时自动跳过，保留原来的生成纹理。请通过 `/metadata` 的 `reference_reprojection.applied` 和 `skip_reason` 确认实际是否应用。

这不是人脸识别、人脸专属 UV 展开、重打光或生成式超分辨率。原图中的阴影、高光可能被保留，相机估计不准时细部也可能错位，所以默认关闭。Alpha、金属度和粗糙度不参与原图投影或锐化。

新模型的纹理嵌入为无损 PNG。历史 GLB 不会被自动改写，可能仍包含 WEBP。相同种子有助于复现，但不承诺不同软硬件版本之间逐字节一致。

## 5. 接口一览

“Cookie + CSRF” 表示同时发送私有会话 Cookie 和 `X-CSRF-Token`。

| 请求 | 认证 | 成功状态 | 用途 |
| --- | --- | --- | --- |
| `GET /api/session` | 无；已有 Cookie 可带上 | 200 | 创建或刷新会话，获取 CSRF |
| `GET /api/health` | 无 | 200 | 真实引擎状态、队列、支持参数 |
| `GET /api/openapi.json` | 无 | 200 | 机器可读的 API 规范 |
| `POST /api/jobs` | Cookie + CSRF | 202；幂等重放为 200 | 上传并提交任务 |
| `GET /api/jobs?limit=20&cursor=...` | Cookie | 200 | 分页列出本会话任务 |
| `GET /api/jobs/{id}` | Cookie | 200 | 轮询任务状态和结果统计 |
| `POST /api/jobs/{id}/retry` | Cookie + CSRF | 202 | 重新排队失败任务 |
| `GET /api/jobs/{id}/image` | Cookie | 200 二进制 | 规范化后的输入 PNG |
| `GET /api/jobs/{id}/thumbnail` | Cookie | 200 二进制 | WEBP 缩略图；旧任务可能回退到 PNG |
| `GET /api/jobs/{id}/model` | Cookie | 200 二进制 | 完成的 GLB，model/gltf-binary |
| `GET /api/jobs/{id}/metadata` | Cookie | 200 | 导出纹理、校验值、投影信息 |
| `DELETE /api/jobs/{id}` | Cookie + CSRF | 200 | 删除排队中、失败或已完成任务与文件 |

当前 API 不支持取消正在运行的任务，删除运行中任务返回 `409 job_running`。删除排队任务可阻止其被 worker 获取。删除不可撤销，也会删除该任务的幂等映射。

任务列表返回 `jobs` 和 `next_cursor`；`limit` 默认为 20，可取 1 至 100。将上页返回的 `next_cursor` 原样传到下一页，直到它为 `null`。若游标对应的任务已删除或过期，请从第一页重新开始。列表分页不影响通过保存的任务 ID 单独访问仍保留的旧任务。

## 6. 状态与时间

`state` 只有四种主要取值：`queued`、`running`、`complete`、`failed`。

常见 `stage` 为 `queued → preprocessing → camera → generating → exporting → uv_unwrap → baking → reprojecting → complete`。投影可选，重试也可能直接从导出检查点继续，因此不要假设每个阶段都会出现。以 `state` 判断完成或失败。

| 字段 | 含义 |
| --- | --- |
| `ahead` | 排队时前方的全站任务数 |
| `created`、`updated` | Unix 秒级时间戳 |
| `attempt_started` | 本轮尝试进入队列的时间；首次为创建时间 |
| `attempts` | 尝试次数，从 1 开始 |
| `duration` | 最近一次服务器处理秒数，不包含排队与下载 |
| `vertices`、`faces`、`bytes` | 成功后的顶点数、三角面数、文件字节数 |
| `texture_encoding` | 已知的纹理编码；历史任务可能为空 |
| `error` | 失败代码，正常时为 null |

活跃任务响应带 `Retry-After: 3`，建议每三秒轮询。`/api/health` 的 HTTP 200 不代表模型已经就绪，必须检查 `ready`。`ready` 或 `busy` 可以继续接收排队任务。`loading` 或 `starting` 表示正在初始化；`waiting_gpu` 表示可用显存不足；`recovering`、`failed` 或 `stopped` 表示暂时不能生成。`offline` 表示 worker 不存在、心跳过期或无效，或进程已经退出。为保持兼容，引擎不可用时提交和重试仍返回 `503 engine_starting`，并带 `Retry-After: 10`。

新导出的模型会在 `GET /api/jobs/{id}/metadata` 的 `metadata.stage_seconds` 中提供各阶段实测处理秒数，不包含排队和下载时间。历史模型可能没有此字段。图片解码和保存使用独立的并发限制，大图上传不会阻塞健康检查和进度轮询。

## 7. 幂等上传与失败重试

上传时建议发送 `Idempotency-Key`，长度 8 至 128 个字符，可用字母、数字、点、下划线、冒号和连字符，UUID 适合用作键。键只在同一个 Cookie 会话中有效。

第一次提交返回 202 和任务 `Location`。相同会话、相同键、完全相同的原始图片字节与等价参数再次提交时，返回已有任务、HTTP 200 和 `Idempotency-Replayed: true`，不会再次生成。即使 worker 暂不可用，也可以重放查询原上传结果。键相同但内容不同返回 `409 idempotency_conflict`。

上传超时或出现 502/504 时，任务可能已经被接收。务必保留原 Cookie、键和参数来恢复，不要立刻换新键创建重复 GPU 工作。任务被删除或到期后，幂等映射也随之移除，不是永久去重。

`POST /api/jobs/{id}/retry` 则是另一种操作：它只接受失败任务，保留 ID、输入和原参数，增加 attempts，清除旧错误与结果统计，重新加入队尾。若之前保留了导出检查点，可跳过重复生成。不能用它重试已完成任务，也不能用它修改生成参数。重试请求网络中断后，先查询任务状态，不要盲目重复 POST。

## 8. 错误与限制

通常错误响应为 `{ "detail": "error_code" }`；表单类型错误可能返回错误列表。Nginx 在请求抵达 Python 前拒绝上传时，也可能返回 HTML。

| 状态码 | 常见代码 | 处理建议 |
| --- | --- | --- |
| 400 | invalid_host、invalid_idempotency_key | 检查主机名与幂等键 |
| 401 | session_required | 创建会话并保留 Cookie |
| 403 | csrf_invalid、origin_invalid | 用同一 Cookie 刷新 CSRF，检查 Origin |
| 404 | job_not_found、cursor_not_found | 检查会话归属；任务可能已删除或到期 |
| 409 | model_not_ready、job_running、retry_unavailable、idempotency_conflict | 按任务状态或原始请求内容处理 |
| 410 | expired、metadata_unavailable | 文件或元数据不可用 |
| 413 | image_too_large | 缩小文件 |
| 422 | invalid_image、invalid_settings 或错误列表 | 修正图片与参数 |
| 503 | engine_starting、storage_low | 检查引擎或存储状态 |
| 502、504 | 代理或上游不可用 | 读取可退避重试；上传应复用幂等键 |

GPU 计算失败一般体现在 HTTP 200 的任务 JSON 中：`state: failed`，并带 `error`，不是传输层错误。请保留失败代码与任务 ID。

输入上限是 20 MiB，即 20 × 1024 × 1024 字节；短边至少 64 像素，解码后不超过 2000 万像素。规范化图像最长边最多 4096。公网代理另有 22 MiB 的整个请求限制，包含 multipart 开销。当前 HTTP API 只支持单图；上游有多视图代码并不意味着此站已开放多视图接口。

当前没有每小时、每会话或全队列任务数量上限，但这不等于无限算力。GPU worker 串行执行，低磁盘空间会拒绝新任务，显存也可能被共享工作负载占用。批量调用应控制提交节奏。

已完成和失败任务在最近一次完成或失败满七天后进入周期清理范围，不保证精确到秒删除；排队或运行中的任务不会被清理。重试保留原始创建时间，但会在本轮结束后重新计算七天保留期。清理与重试会协调处理，避免已接受的重试被同时发生的清理删除输入。每轮有 30 分钟应用层超时，深度卡死的原生 CUDA 调用仍可能需要运维恢复。下载完成后请自行保存模型。

## 9. 集成要点与来源

一个私有工作区使用一个持久会话；保管 Cookie，写操作带 CSRF；上传使用幂等键；立即保存任务 ID；轮询到完成或失败；完成后下载并校验 GLB；通过导出元数据确认投影是否实际生效。

生成角色后，请检查眼睛、头发、手部、未见背面、拓扑和目标引擎中的材质。服务不保证完美相似度、动画友好拓扑、骨骼、蒙皮或描绘内容的商用权利。

HTTP 行为以项目 `server.py`、`api_contract.py` 为准；生成和导出以 `worker.py`、`texture_settings.py`、`reference_projection.py` 为准。生成引擎来源为 [TencentARC/Pixal3D](https://github.com/TencentARC/Pixal3D)，可见性栅格化使用 [NVIDIA nvdiffrast](https://nvlabs.github.io/nvdiffrast/)。依赖的原有许可证继续适用。
