v1 stable最后更新 2026-10-24
API DEVELOPER PLATFORM
DishPhoto API
用一套 REST API 把菜品视觉接入你的点餐、外卖或内容系统:上传原图、提交生成任务、订阅进度、拿到 4K 成品。
Base URL
https://api.dishphoto.example/api/v1
所有请求使用 HTTPS;金额为最小货币单位整数;时间为 RFC 3339 UTC;写操作支持
Idempotency-Key。快速开始
三步完成一次生成:预签名上传 → 创建任务 → 订阅进度。
创建任务
# 1. 创建生成任务 curl -X POST https://api.dishphoto.example/api/v1/tasks \ -H "Authorization: Bearer $DP_API_KEY" \ -H "Idempotency-Key: 4f2c-8842" \ -d '{ "scene": "retouch", "source_asset_id": "b0f1...", "template_code": "delivery_white_v3", "ratio": "1:1", "output_4k": true }'
Node.js
const res = await fetch('https://api.dishphoto.example/api/v1/tasks', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.DP_API_KEY}`, 'Idempotency-Key': '4f2c-8842' }, body: JSON.stringify({ scene: 'retouch', source_asset_id: 'b0f1...', ratio: '1:1' }) }); const task = await res.json();
Python
import requests resp = requests.post( "https://api.dishphoto.example/api/v1/tasks", headers={"Authorization": f"Bearer {API_KEY}"}, json={"scene": "retouch", "source_asset_id": "b0f1...", "ratio": "1:1"}, ) task = resp.json()
认证
在控制台创建 API Key,通过 Authorization: Bearer <key> 传递。Key 只显示一次,请存入密钥管理服务。
创建于 2026-10-20 · 最近使用 2 分钟前 · 权限 tasks:write assets:read
不要在浏览器或移动端代码中暴露 Key;前端请通过你自己的后端代理调用。
生成任务
POST
/tasks创建生成任务,返回 202 与任务 ID;积分在提交时预扣。
GET
/tasks/{task_id}查询任务状态、候选结果与错误信息。
GET
/tasks/{task_id}/eventsSSE 订阅进度:progress / completed / failed。
POST
/tasks/{task_id}/cancel取消排队或运行中的任务,积分全额退回。
任务状态机:queued → running → postprocessing → succeeded,失败进入 failed 并自动退回积分。
素材
POST
/assets/presign获取上传预签名 URL,有效期 15 分钟。
GET
/assets分页查询素材,支持类型、门店与关键词筛选。
DEL
/assets/{asset_id}软删除素材,进入回收站 30 天。
积分
GET
/credits/account查询可用、冻结与累计积分。
GET
/credits/ledger查询流水,按类型与时间筛选。
积分消耗系数:2K 标准图 1 分、4K 2 分、局部重绘 0.5–1 分。
Webhook
任务完成、失败或退款时回调。请求带 X-DP-Signature(HMAC-SHA256),时间戳窗口 5 分钟。
task.completed
{
"event": "task.completed",
"task_id": "8c2e-8842",
"status": "succeeded",
"credits_settled": 2,
"results": [{ "candidate": 1, "url": "https://cdn.../1.jpg" }]
}
错误码
| Code | HTTP | 含义 |
|---|---|---|
| CREDIT_001 | 402 | 积分不足 |
| TASK_002 | 503 | 队列繁忙,请稍后重试 |
| TASK_003 | 500 | 生成失败,积分已退回 |
| ASSET_001 | 400 | 文件类型不支持 |
| SAFE_001 | 422 | 内容不合规 |
| RATE_001 | 429 | 请求过于频繁 |
限流与配额
默认 60 请求 / 分钟 / Key,任务并发按套餐:Starter 2、Business 5、Scale 10。响应头返回 X-RateLimit-Remaining 与 Retry-After。