lunanting/ai-chatbot

Fork 0

134 54cd02d09d feat: improve Claw workflows and reliability

2026-08-07 14:52:17 +08:00

7.0 KiB

Raw Permalink Blame History

第三方生图 API 调用说明

本文档用于提供给第三方调用方，说明如何对接我们系统开放的生图能力。

1. 接口概览

当前开放两条接口：

获取可用模型列表
GET /api/external/image/models
发起生图
POST /api/external/image/generate

这套接口是 图生图接口。第三方调用方只需要上传参考图和提示词，不需要也不允许指定内部模型名。
我们服务端会按后台默认优先级自动选择模型，优先尝试 GPT-image-2，失败后自动故障迁移到其他可用图生图模型，尽量返回图片。
如果调用方提交 model / modelId / modelRef 等模型字段，接口会直接返回 400。
生成结果图片会先上传到我们的储存桶，再写入我们的数据库与媒体资产表。

2. 鉴权方式

支持以下两种方式，任选其一：

方式 A：Authorization Bearer

Authorization: Bearer YOUR_API_KEY

方式 B：x-api-key

x-api-key: YOUR_API_KEY

如果 API Key 无效、已停用，或后台未启用第三方生图 API，接口会返回 401 或 403。

3. 获取模型列表（可选）

请求

curl -X GET "https://ai.yydd.ai/api/external/image/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

成功响应示例

{
  "success": true,
  "data": {
    "models": [
      {
        "id": "9b8f7c10-1111-4d22-9abc-1234567890ab",
        "modelId": "seedream-5.0-lite",
        "displayName": "Seedream 5.0 Lite",
        "description": "轻量版商品生图模型",
        "providerType": "volcano-vision",
        "providerName": "火山视觉",
        "avatarUrl": "https://ai.yydd.ai/uploads/xxx.png",
        "imageGenConfig": {
          "creditCost": 20
        }
      }
    ]
  }
}

字段说明

id：系统内部模型 UUID
modelId：上游模型 ID
displayName：系统中展示给用户的模型名称
providerType：模型服务商类型
providerName：模型服务商显示名称
imageGenConfig：当前模型的生图配置，包含积分等后台配置

说明：

这个接口主要用于联调排查或查看当前可用能力
被后台设置为“前台隐藏”的模型不会出现在这个列表里
正式调用生图接口时，第三方 无需传模型名

4. 发起生图

请求地址

POST https://ai.yydd.ai/api/external/image/generate
Content-Type: application/json 或 multipart/form-data
Authorization: Bearer YOUR_API_KEY

请求参数

{
  "prompt": "保留原空间结构，将这张衣帽间草图改成真实摄影效果，木色更高级，灯光柔和",
  "negativePrompt": "不要人物，不要文字水印，不要畸变",
  "imageCount": 2,
  "aspectRatio": "16:9",
  "imageSize": "2K",
  "referenceImages": [
    "https://ai.yydd.ai/uploads/source-1.jpg",
    "https://ai.yydd.ai/uploads/source-2.jpg"
  ],
  "metadata": {
    "bizId": "partner-order-20260518-001"
  }
}

参数说明

prompt：正向提示词，必填
negativePrompt：反向提示词，可选
imageCount：生成张数，可选，默认 1，最大 8
aspectRatio：宽高比，可选，例如 1:1、16:9
imageSize：图片规格，可选，例如 1K、2K
referenceImages：参考图地址数组，必填，至少 1 张，最多 14 张
metadata：业务扩展字段，可选，会原样记录到请求日志里

multipart/form-data 调用方式

可直接上传图片文件，不必先把图片上传到公网：

文本字段：prompt、negativePrompt、imageCount、aspectRatio、imageSize
文件字段：images（可重复上传多张）
也支持混合传参：文件字段 images + URL 字段 imageUrls

5. 生图成功响应

{
  "success": true,
  "data": {
    "requestId": "5e8a63f6-1111-4d6c-8bb4-1234567890ab",
    "model": {
      "id": "9b8f7c10-1111-4d22-9abc-1234567890ab",
      "modelId": "seedream-5.0-lite",
      "displayName": "Seedream 5.0 Lite",
      "description": "轻量版商品生图模型",
      "providerType": "volcano-vision",
      "providerName": "火山视觉",
      "avatarUrl": null,
      "imageGenConfig": {
        "creditCost": 20
      }
    },
    "images": [
      {
        "id": 1,
        "originalUrl": "https://ai.yydd.ai/uploads/2026xxxx-orig.jpg",
        "thumbnailUrl": "https://ai.yydd.ai/uploads/2026xxxx-orig.jpg",
        "imageSize": "2K"
      },
      {
        "id": 2,
        "originalUrl": "https://ai.yydd.ai/uploads/2026yyyy-orig.jpg",
        "thumbnailUrl": "https://ai.yydd.ai/uploads/2026yyyy-orig.jpg",
        "imageSize": "2K"
      }
    ],
    "generatedImageIds": [
      "3d3a0f24-1111-4c0c-8d9d-1234567890ab"
    ],
    "generatedAssetIds": [
      "b7b19e10-1111-4db8-aeb2-1234567890ab"
    ],
    "attempts": [
      {
        "modelId": "07e2304a-a63a-4fd3-9c76-63ba98de464d",
        "modelRuntimeId": "openai/gpt-image-2/edit",
        "displayName": "GPT-image-2",
        "success": true
      }
    ]
  }
}

返回字段说明

requestId：本次请求日志 ID，可用于后台排查
images：最终生成结果
- originalUrl：原图地址
- thumbnailUrl：缩略图地址
- imageSize：记录的图片规格
generatedImageIds：写入 GeneratedImage 表后的记录 ID
generatedAssetIds：写入媒体资产表后的记录 ID
attempts：本次自动选模 / 故障迁移尝试明细

6. 失败响应示例

{
  "success": false,
  "error": "未找到匹配的生图模型"
}

常见失败原因：

API Key 缺失或无效
第三方生图 API 后台未开启
未上传参考图
上游模型生成失败
上游返回内容中未解析出图片

7. 调用建议

这条接口按“图生图”设计，请始终上传至少 1 张参考图
第三方不要传模型名，交给服务端按默认优先级和故障迁移处理
将返回的 requestId 保存到业务日志，便于双方排查问题
返回的图片地址已经是我们系统储存桶地址，可以直接展示或下载
服务端会按模型错峰发起并发请求，不需要调用方等待上一张图片生成完成后再提交；请将 HTTP 请求超时设置为至少 1200 秒
400 且提示“至少上传 1 张参考图”表示请求没有成功传入图片文件或图片 URL；499 通常表示调用方在结果返回前主动断开了连接

8. 后台能力

后台已支持以下管理能力：

启用/关闭第三方生图 API
配置默认归属用户邮箱
配置多个 API Key
单独启用/停用某个 Key
查看最近请求日志、生图明细、耗时、失败原因、结果地址

9. 对接备注

这套接口使用的是我们系统当前启用的生图模型，模型列表会随后台配置变化而变化
被后台设置为“前台隐藏”的模型，默认也禁止提供给第三方 API 使用
如果需要增加调用频控、签名校验、白名单 IP、异步回调等能力，可以继续在这套 API 上扩展

7.0 KiB Raw Permalink Blame History Unescape Escape