把 YIFU 的出图能力，
接进你已有的系统。

01 介绍

YIFU API 允许你从自己的系统（ERP / OMS / 内部工具）直接调用出图流水线：

1. 用 API Key 鉴权（每个组织一个，可多把）
2. 把平铺图 上传到 R2（拿到 upload_id）
3. 创建任务，传 SKU 信息 + 模特 + 场景 + 平台
4. 轮询任务或订阅 Webhook等回调
5. 任务完成后从 job.images[] 里取出预签名 URL 下载或转存

所有响应是 JSON。时间戳是 Unix milliseconds (UTC)。金额单位是积分（¥1 = 10 积分）。

02 认证

所有请求需要带 Authorization: Bearer <api_key>。API Key 在控制台 设置 · API & 集成页面一次性展示，后续只显示前 4 + 后 4 位。

curl https://api.yifu.app/v1/jobs \
  -H "Authorization: Bearer bk_live_a1b2c3d4..."

每把 Key 可配置：

• 权限范围：只读 / 读写 / 全权（影响能否创建任务、删除资源等）
• IP 白名单（企业版）
• 速率上限（见 速率限制）

03 上传图片

上传一张原图（平铺 / 挂拍），拿到 upload_id 用于建任务。支持 image/jpeg / image/png / image/webp，单张不超过 20 MB。

curl https://api.yifu.app/v1/uploads \
  -H "Authorization: Bearer $BUPI_API_KEY" \
  -F "file=@./tshirt-flat.jpg"

{
  "upload_id": "up_2871hgT9aP",
  "url": "https://r2.yifu.app/uploads/up_2871hgT9aP.jpg",
  "size_bytes": 1840261,
  "expires_at": 1779870000000
}

expires_at 是预签名 URL 的过期时间（默认 7 天）。建任务后 R2 文件会被永久保留并归入任务。

04 创建任务

提交一个出图任务。建任务立即扣 5 积分用于草图。精修阶段在草图确认后单独触发并扣 48 积分（8 张 × 6 积分）。

curl https://api.yifu.app/v1/jobs \
  -H "Authorization: Bearer $BUPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "BP-2871",
    "title": "亚麻短袖衬衫 · M 码",
    "upload_id": "up_2871hgT9aP",
    "platform": "tiktok_shop_us",
    "model_id": "m-04",
    "scene_id": "scene-us-suburban",
    "english_text": {
      "hang_tag": "100% Linen · BP-2871 · Size M",
      "promo": "FALL 2026 · LOOSE FIT"
    },
    "metadata": { "internal_ref": "erp-job-19384" }
  }'

{
  "id": "job_9aT2bX",
  "status": "draft_running",
  "credits_spent": 5,
  "credits_balance": 18345,
  "created_at": 1779787613229
}

05 任务列表

分页列出本组织的任务。

06 任务详情

取单个任务的完整状态。前端轮询建议间隔 1.5s。

{
  "id": "job_9aT2bX",
  "sku": "BP-2871",
  "title": "亚麻短袖衬衫 · M 码",
  "status": "done",
  "progress": { "drafts_done": 8, "refined_done": 8 },
  "drafts": [ { "id": "img_d_01", "url": "...", "watermark": true }, ... ],
  "images": [
    {
      "id": "img_r_01",
      "url": "https://r2.yifu.app/jobs/job_9aT2bX/01.jpg?...",
      "qa_score": 94,
      "platform_crops": {
        "amazon_1x1": "https://r2.yifu.app/.../amazon-01.jpg",
        "tiktok_9x16": "https://r2.yifu.app/.../tiktok-01.jpg"
      }
    }
  ],
  "created_at": 1779787613229,
  "completed_at": 1779787812391
}

所有 URL 都是预签名链接，7 天有效。如果你的系统需要长期持有，请下载到你的存储。

07 触发精修

草图确认后调一次进入精修阶段，扣 48 积分。同一任务只能调一次，重复调返回 409 conflict。

curl https://api.yifu.app/v1/jobs/job_9aT2bX/refine \
  -H "Authorization: Bearer $BUPI_API_KEY" \
  -X POST

08 Webhooks

在控制台 Webhooks 区配置一个 HTTPS 接收端，订阅以下事件：

请求体是 POST application/json，带签名头 X-Yifu-Signature（HMAC-SHA256 over body）。请用你的 Webhook Secret 验签后再信任内容。

POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Yifu-Signature: sha256=8f3a...
X-Yifu-Event: job.done
X-Yifu-Delivery: whd_5tQ2

{
  "type": "job.done",
  "id": "evt_8aZ9pK",
  "created_at": 1779787812391,
  "data": {
    "job_id": "job_9aT2bX",
    "images_count": 8
  }
}

我们要求 2 秒内返回 2xx。失败会按 30s / 2min / 10min / 1h / 6h 重试 5 次。

09 错误码

所有错误响应体形如：

{
  "error": {
    "code": "insufficient_credits",
    "message": "至少需要 53 积分，当前余额 12",
    "request_id": "req_011Cb..."
  }
}

报问题时请附上 request_id，能让客服直接定位日志。

10 速率限制

按 API Key 限制并发与每分钟调用量：

触发限流返回 429，响应头会带 Retry-After（秒）。请遵守此头，不要循环重试。