AI Agent 接口说明（OpenAPI）

这份文档是给 AI Agent（Claude Code / OpenClaw / 自建 Agent）直接阅读的最小可用说明。所有接口统一返回：

{ "code": 0, "message": "success", "data": {}, "requestId": "req_xxx" }

错误码：判断失败时，应使用「code 存在且不等于 0」——若响应里 code 为 null 或省略，不要当作错误（避免把 code != 0 误判为失败）。

字段命名：data 内不少接口同时兼容 camelCase 与 snake_case，解析时建议回退读取，例如：

任务 ID：jobId / job_id / taskId / task_id
上传 URL：signedUrl / signed_url
结果图 URL：imageUrl / image_url；结果列表优先 data.results（每项常含 url），勿只认 result.images

鉴权

Header（二选一）：
- Authorization: Bearer ak_xxx（推荐）
- X-API-Key: ak_xxx（兼容）

Base Path

/api/v1/open

图片上传（本地图片）

当你有本地图片文件（如 ./photo.jpg）时，需先上传获取可访问 URL，再调用各工具接口。

POST /api/v1/images/upload

Content-Type: multipart/form-data
Body: file 字段（图片文件）
鉴权: 同 OpenAPI，Authorization: Bearer ak_xxx

响应示例：

{
  "code": 0,
  "data": {
    "signedUrl": "https://...",
    "signed_url": "https://...",
    "bucket": "...",
    "path": "...",
    "md5": "..."
  }
}

使用返回的 data.signedUrl 或 data.signed_url 作为各接口的 image_url 或 referenceImage。

图片输入规则

图片来源	处理方式
本地文件（如 `./a.png`）	先调用 `POST /api/v1/images/upload` 上传，用返回的 `signedUrl` / `signed_url`
远程 URL（如 `https://example.com/photo.jpg`）	直接传给接口，无需上传

异步任务与轮询端点

当 POST 返回的 data.status 为 pending 或 processing 时，应用同一 API Key 轮询直到 completed 或 failed。不要依赖「仅在请求里开启 async_mode 才轮询」——服务端可能始终返回异步任务。

能力	POST 路径	轮询 GET 路径（将 `{id}` 换为响应中的任务 ID）
去背景、高清放大	`/api/v1/open/image/remove-bg`、`/api/v1/open/image/upscale`	`/api/v1/open/image/tasks/{id}`
智能扩图、图片翻译	`/api/v1/open/image/outpainting`、`/api/v1/open/image/translation`	`/api/v1/open/ai/generations/{id}`（勿用 `/image/tasks`）
文生图、图生图	`/api/v1/open/ai/generations`	`/api/v1/open/ai/generations/{id}`

任务 ID：从首次（及轮询）响应的 data 读取，兼容 jobId / job_id / taskId / task_id。

结果图片：优先 data.results（一般为对象数组，每项含 url，可兼容 imageUrl / image_url）；若无 results，再回退 data.result 上的 imageUrl / image_url 等。

去背景 / 放大轮询示例：

curl -sS "https://<host>/api/v1/open/image/tasks/matting-xxxxxxxx-20260320120000" \
  -H "Authorization: Bearer ak_xxx"

扩图 / 翻译 / 文生图 / 图生图轮询：将路径换为 /api/v1/open/ai/generations/{id}。

轮询建议：间隔 2–5 秒；每次响应同样用「code 存在且非 0」判断错误。

模型发现与选型（文生图/图生图）

text-to-image 和 image-to-image 并不只支持单一模型。 Agent 在发起 /api/v1/open/ai/generations 前，应该先查询可用模型：

GET /api/v1/open/ai/models
可选 Query：type=text_to_image、type=image_edit 等（按能力过滤）

建议执行流程（给 Agent）：

调用 /api/v1/open/ai/models 获取当前环境可用模型清单。
从返回结果中筛选支持当前任务的模型（text_to_image 或 image_to_image）。
根据 model 字段值（对应表中「内部 model_id」），到下方“厂商模型与官方文档”定位对应官方文档。
按官方文档要求校验参数格式（分辨率、比例、图片输入字段、异步机制等）。
最后再调用 /api/v1/open/ai/generations。

备注：若“官方文档”和“本系统行为”不一致，以服务端实际返回为准。

厂商模型与官方文档（用于 Agent 自助查询）

以下为整理内容：

Bytedance（火山引擎 Ark）

doubao-seedream-4-0-250828（text_to_image / image_to_image）官方文档：Seedream 4.0 图像生成 API
doubao-seedream-4-5-251128（text_to_image / image_to_image）官方文档：即梦 4.5 官方文档

Aliyun（DashScope）

qwen-image / qwen-image-plus / qwen-image-max（text_to_image）官方文档：Qwen Image API
qwen-image-edit-plus（image_to_image / image_edit）官方文档：Qwen Image Edit API
wanx-v2（text_to_image / image_to_image / image_edit）官方文档：通义万相 V2 文生图
wanx-v2.5（text_to_image / image_to_image / image_edit）官方文档：通义万相 V2.5 文生图/编辑

给 Agent 的执行指令（可直接复制）

图片输入规则：本地文件需先 POST /api/v1/images/upload 上传，用 data.signedUrl 或 data.signed_url；远程 URL 直接传入。

若 POST 返回 data.status 为 pending/processing：必须轮询——抠图/放大用 GET /api/v1/open/image/tasks/{taskId|task_id}；扩图/翻译/文生图/图生图用 GET /api/v1/open/ai/generations/{jobId|task_id}。鉴权与创建任务相同。结果图优先 data.results[].url。

你在调用 /api/v1/open/ai/generations 做文生图或图生图前，请先：
1) GET /api/v1/open/ai/models?type=text_to_image（或 type=image_edit），拿到可用模型；
2) 选择支持目标能力的 model（列表中的 type 字段值）；
3) 到 docs/server-api/BYTEDANCE_ALIYUN_MODEL_API_REFERENCE.md 里找到该模型的官方文档链接，确认参数格式；
4) 再构造 /api/v1/open/ai/generations 请求。

重要：请求体使用 model（不是 model_id），prompt 放在顶层（不要嵌套在 parameters 里）。
文生图：type=text_to_image，顶层 prompt；
图生图：type=image_to_image，顶层 prompt + referenceImage。

重要约束：image_url / referenceImage

remove-bg、upscale、outpainting、translation 等接口要求 image_url 为可公网访问的 URL；图生图要求 referenceImage 同理。

本地图片：先调用 POST /api/v1/images/upload 上传，再用返回的 data.signedUrl / data.signed_url
远程 URL：若已是可访问的 https://... 地址，直接传入，无需上传

remove-bg（智能抠图）

POST /api/v1/open/image/remove-bg

本地图片需先上传（POST /api/v1/images/upload），远程 URL 可直接传入 image_url。

请求体示例：

{
  "image_url": "https://example.com/input.jpg",
  "output_format": "png",
  "return_mask": false,
  "only_mask": false,
  "async_mode": false
}

返回 data 关键字段（兼容 camelCase / snake_case）：

taskId / task_id
status: pending|processing|completed|failed
完成时结果图：优先 results 数组中第一项的 url；或 result.imageUrl / result.image_url、result.maskUrl / result.mask_url（return_mask=true 时有 mask）

status 为 pending / processing：用 GET /api/v1/open/image/tasks/{taskId|task_id} 轮询（与是否设置 async_mode 无关）。

upscale（高清放大）

POST /api/v1/open/image/upscale

本地图片需先上传，远程 URL 可直接传入 image_url。

请求体示例：

{
  "image_url": "https://example.com/input.jpg",
  "scale": 2,
  "tile_size": 0,
  "tile_pad": 10,
  "output_format": "png",
  "async_mode": false
}

async_mode：可选；即使未传或为 false，若响应 status 仍为 pending / processing，也应轮询 GET /api/v1/open/image/tasks/{taskId|task_id}。

返回 data：taskId/task_id、status、results 或 result 中的图片 URL 字段（camelCase / snake_case 均可能出现）。

outpainting（智能扩图）

POST /api/v1/open/image/outpainting

本地图片需先上传，远程 URL 可直接传入 image_url。

请求体示例：

{
  "provider": "aliyun",
  "model_id": "wanx-outpaint",
  "image_url": "https://example.com/input.jpg",
  "direction": "all",
  "expand_ratio": 0.5,
  "angle": 0,
  "output_ratio": null,
  "best_quality": false
}

异步：若 data.status 为 pending / processing，轮询 GET /api/v1/open/ai/generations/{jobId|taskId|task_id}（不要使用 /api/v1/open/image/tasks/...）。完成后优先从 data.results[].url 取图。

translation（图片翻译）

POST /api/v1/open/image/translation

本地图片需先上传，远程 URL 可直接传入 image_url。

请求体示例：

{
  "provider": "aliyun",
  "model_id": "qwen-mt-image",
  "image_url": "https://example.com/text-image.jpg",
  "source_language": "auto",
  "target_language": "en",
  "domain_hint": null,
  "sensitive_word_filter": false,
  "term_intervention": null
}

异步：若 data.status 为 pending / processing，轮询 GET /api/v1/open/ai/generations/{jobId|taskId|task_id}。完成后优先 data.results[].url。错误判断：code is not None and code != 0。

text-to-image（文生图）

POST /api/v1/open/ai/generations

最小请求体示例（注意：使用 model 而非 model_id，prompt 在顶层）：

{
  "type": "text_to_image",
  "model": "wanx-v2.5",
  "prompt": "一只红嘴蓝鹊站在树枝上，背景是蓝天白云"
}

字段说明：

type: text_to_image（必填）
model: 模型名称（必填），如 wanx-v2.5、qwen-image-plus、doubao-seedream-4，通过 GET /api/v1/open/ai/models 获取
prompt: 提示词（必填），放在顶层，不要嵌套在 parameters 里

任务查询：

GET /api/v1/open/ai/generations/{jobId|job_id|task_id}（与创建响应中的 ID 字段一致）
完成后优先从 data.results 读取输出（如 results[0].url），兼容旧结构中的单对象 result

image-to-image（图生图）

POST /api/v1/open/ai/generations

本地图片需先上传，远程 URL 可直接传入 referenceImage。

最小请求体示例（注意：使用 model 而非 model_id，prompt 与 referenceImage 在顶层）：

{
  "type": "image_to_image",
  "model": "wanx-v2.5",
  "prompt": "把天空变成日落金色，保持主体不变",
  "referenceImage": "https://example.com/input.jpg"
}

字段说明：

type: image_to_image（必填）
model: 模型名称（必填），如 wanx-v2.5、qwen-image-edit-plus
prompt: 编辑提示词（必填），放在顶层
referenceImage: 参考图片 URL（必填），放在顶层

任务查询：

GET /api/v1/open/ai/generations/{jobId|job_id|task_id}；结果列表为 data.results