API 接入指南

一、接口能做什么

开放接口提供两个能力：

• 提交生成任务（POST /api/v1/tasks）—— 提交一条出图需求，立即返回任务标识；
• 查询任务结果（GET /api/v1/tasks/:id）—— 轮询任务状态，完成后取走图片地址。

任务是异步的：提交成功只代表已受理，图片一般几十秒内生成完成。完成后通过轮询接口获取结果。

📌 本接口面向第三方系统调用，用 API Key 鉴权；调用产生的积分从你的账号余额扣除（与网页版共用同一个钱包）。

二、快速接入（四步）

三、鉴权

所有请求都需携带 API Key（形如 sk_xxxxxxxxxxxxxxxx），放在请求头 Api-Key 中：

Api-Key: sk_xxxxxxxxxxxxxxxx

⚠️ 请使用个人中心生成的专用 API Key，不要用网页端的登录态或浏览器令牌调用本接口 —— 那些凭据不适用于第三方调用，也不持久。

四、提交任务

项	值
地址	POST /api/v1/tasks
协议	HTTPS
请求体	application/json，UTF-8

请求参数

{
  "model": "Seedream-5.0",
  "prompt": "一只戴墨镜的橘猫站在山顶看日落，电影感光线，写实风格",
  "size": "1:1",
  "count": 2,
  "ref_images": ["https://example.com/a.png", "https://example.com/b.png"]
}

字段	类型	必填	说明
model	string	是	模型标识，见第六节。未知标识 → 422。
prompt	string	是	画面描述，越具体越好（主体、动作、环境、光线、风格）。
size	string	否	图片尺寸，用「宽:高」比例表示，如 1:1、2:3。不填则 自动匹配（由模型决定）。
count	number	否	生成数量 1～10，默认 1。
ref_images	string[]	否	参考图地址数组（图生图），最多 3 张，需公网可访问。

📌 size 以「宽:高」比例传入，例如 1:1（正方形）、2:3（竖版）、3:2（横版）、16:9、9:16 等。具体可选比例以提交页下拉框为准（不同模型略有差异）；不填则 自动匹配，由模型自行决定尺寸。

返回（HTTP 201 Created）

{
  "task_id": "tsk_7QfG1h2x9kLm3",
  "status": "pending",
  "charge_ref": "chr_20261021_000123"
}

字段	说明
task_id	本次任务的唯一标识，用于查询结果。
status	提交成功时为 "pending"（已受理，排队中）。
charge_ref	本次扣费凭据，用于对账与退款排查。

五、查询任务

GET /api/v1/tasks/:id（:id 替换为提交时返回的 task_id），鉴权方式相同。

返回（HTTP 200）

{
  "task_id": "tsk_7QfG1h2x9kLm3",
  "status": "done",
  "images": ["https://cdn.example.com/out/1.png", "https://cdn.example.com/out/2.png"]
}

status	含义	你能做什么
pending	已受理，排队中	继续等待
generating	生成中	继续等待
done	生成完成	从 images 取图片地址
failed	生成失败	看 error 里的原因；积分已自动退回

• images：仅 done 时返回，为生成图片的地址数组（数量与提交的 count 一致）。
• error：仅 failed 时返回，为失败原因说明。

💡 生成一般几十秒内完成。轮询建议 30 秒左右一次，不要高频轮询（会触发限流）。已拿到图片地址后请及时转存，平台不承诺永久保留。

六、支持的模型

model 标识	单价	说明	是否公开
Seedream-4.0	6 积分/张	通用出图，最便宜，适合批量试	✅ 公开
Seedream-4.5	8 积分/张	画质更精细	✅ 公开
Seedream-5.0	10 积分/张	当前默认模型，写实质感与细节更强	✅ 公开
Hy-Image-3.5	20 积分/张	新接入的图像模型（预览版）	✅ 公开
Hy-Image-3.0	22 积分/张	新接入的图像模型	✅ 公开
万相-2.6	22 积分/张	通用出图，性价比高	🔒 需授权
GPT-Image-2	20 积分/张	图像模型	🔒 需授权
GPT-Image-2.5	25 积分/张	图像模型	🔒 需授权

⚠️ 默认只开放标记为「公开」的模型；「需授权」的模型须为你的 Key 显式开通后才可使用。总消耗 = 单价 × count。

七、计费与余额

• 调用时按「模型单价 × count」从你的账号余额扣分 —— 与网页版共用同一个余额，不另设账号；
• 提交任务时先扣分，余额不足 → 402，任务不会创建；
• 生成失败自动全额退分，可凭返回的 charge_ref 对账；
• 充值：在个人中心用卡密充值，比例与网页版一致（1 元 = 100 积分）。

八、限流与配额

按 API Key 维度限制请求频率与月度调用量，触发限制返回 429（响应头 Retry-After 给出建议重试秒数）：

• 请求频率：600 次/分钟（提交与查询都计）；
• 月度配额：10,000 个任务/月（只计提交，查询不占）。

额度不够用可联系管理员调整。

九、错误码

HTTP	code	含义
401	NO_KEY / BAD_KEY	缺 API Key 或 Key 无效
402	NO_BALANCE	账号余额不足
422	BAD_PARAMS	参数错误（model 未知、prompt 缺失、count 超限、ref_images 超过 3 张等）
429	RATE	触发限流或月度配额用尽
5xx	SERVER_ERR	服务端处理失败（此时不会扣分，可安全重试）

调用示例（提交 + 轮询）：

# 1. 提交
curl -X POST https://yuanshuo-ai.app.workbuddy.host/api/v1/tasks \
  -H "Api-Key: sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"Seedream-5.0","prompt":"一只戴墨镜的橘猫站在山顶看日落","size":"1:1","count":1}'
# → 201 {"task_id":"tsk_7QfG1h2x9kLm3","status":"pending","charge_ref":"chr_20261021_000123"}

# 2. 轮询（建议 5 秒一次）
curl https://yuanshuo-ai.app.workbuddy.host/api/v1/tasks/tsk_7QfG1h2x9kLm3 \
  -H "Api-Key: sk_xxxxxxxxxxxxxxxx"
# → 200 {"task_id":"tsk_7QfG1h2x9kLm3","status":"done","images":["https://.../1.png"]}

十、常见问题