Softform Render API · v1

无需打开网页，直接生成抱枕视图与旋转视频。

API 与工作台共用同一套模型、织物材质、固定光源和地面投影。全程非 AI、不消耗 Token、不进行物理烘焙。

Base URL

https://pillowapi.8inpod.cc

公网调用统一使用 HTTPS；机器可读定义位于 /openapi.json。

认证

对外调用必须传入 X-API-Key。服务端通过 SOFTFORM_API_KEY 配置；未配置时仅允许本机回环请求。

HTTP Header

X-API-Key: YOUR_API_KEY

接口

POST/api/v1/renders/stills200 · application/zip

同步返回 front.png、back.png、side.png 和 manifest.json。背面是模型真实旋转 180°；侧面重点展示侧缝。

POST/api/v1/renders/turntable202 · JSON

GET/api/v1/render-jobs/{job_id}200 · JSON

GET/api/v1/render-jobs/{job_id}/result200 · video/mp4

公共参数

生成接口均使用 multipart/form-data。

字段	类型	默认	说明
image	PNG 文件	必填	含 Alpha 通道的设计图；透明区域不生成模型，最大 64 MB。
fullness_percent	number	72	填充饱满度，15–150。
longest_edge_cm	number	40	成品最长边，1–400 cm。
seam_allowance_cm	number	0.7	内缩缝份，大于 0 且小于最长边的 1/4。
max_thickness_cm	number	30	厚度安全上限，不超过最长边的 75%。
quality	enum	standard	draft、standard 或 fine。
fabric	enum	canvas	peach、canvas 或 velvet。
texture_strength_percent	number	100	织物纹理明显程度，0–200。
lighting_strength_percent	number	100	固定光源强度，50–150。
width / height	integer	1024 / 1024	单边 256–4096，总像素不超过 16,777,216。

视频额外参数：fps 1–60（默认 24）；duration_seconds 1–20（默认 4）；direction 为 clockwise 或 counterclockwise；总帧不超过 600。

视频任务流程

1. 提交 PNG，获得 jobId、statusUrl 和 resultUrl。
2. 每 1 秒查询状态：queued → running → succeeded / failed。
3. succeeded 后请求 resultUrl 下载 MP4。结果保留 24 小时。

202 Accepted

{
  "schema": "softform.render-job.v1",
  "jobId": "job_01...",
  "status": "queued",
  "statusUrl": "/api/v1/render-jobs/job_01...",
  "resultUrl": "/api/v1/render-jobs/job_01.../result",
  "cacheKey": "sha256..."
}

错误码

400	empty_file / invalid_request	文件为空或请求格式错误。
401	invalid_api_key	API Key 缺失或无效。
404	job_not_found	任务不存在。
409	job_not_complete	视频尚未生成或生成失败。
410	job_expired	结果已超过 24 小时保留期。
413	file_too_large	输入文件超过限制。
422	invalid_*	图片、尺寸或外观参数不合法。
503	render_queue_full / render_worker_unavailable	渲染槽位繁忙或后台渲染器暂不可用。

503 响应会提供 Retry-After；建议使用指数退避，不要同时占满 GPU 渲染槽位。

调用示例

cURL · 静态图

curl -X POST "$BASE_URL/api/v1/renders/stills" \
  -H "X-API-Key: $SOFTFORM_API_KEY" \
  -F "[email protected];type=image/png" \
  -F "fullness_percent=72" \
  -F "seam_allowance_cm=0.7" \
  -F "fabric=canvas" \
  -F "width=1024" -F "height=1024" \
  --output pillow-views.zip

cURL · 提交视频

curl -X POST "$BASE_URL/api/v1/renders/turntable" \
  -H "X-API-Key: $SOFTFORM_API_KEY" \
  -F "[email protected];type=image/png" \
  -F "fps=24" -F "duration_seconds=4"

Python · 完整轮询

import os, time, requests

base = os.getenv("SOFTFORM_BASE_URL", "https://pillowapi.8inpod.cc")
headers = {"X-API-Key": os.environ["SOFTFORM_API_KEY"]}
with open("design.png", "rb") as image:
    response = requests.post(
        base + "/api/v1/renders/turntable",
        headers=headers,
        files={"image": ("design.png", image, "image/png")},
        data={"fps": 24, "duration_seconds": 4},
        timeout=60,
    )
response.raise_for_status()
job = response.json()

while True:
    state = requests.get(base + job["statusUrl"], headers=headers, timeout=15).json()
    if state["status"] == "succeeded": break
    if state["status"] == "failed": raise RuntimeError(state["error"]["message"])
    time.sleep(1)

video = requests.get(base + job["resultUrl"], headers=headers, timeout=120)
video.raise_for_status()
open("turntable.mp4", "wb").write(video.content)

请在服务端保管 API Key，不要写入前端代码、URL 或公开仓库。v1 不会直接发布破坏性字段变更。