图像生成与编辑

当图像模型出现在你的 GET /v1/models 返回中时，可使用 OpenAI 兼容的图像路由。先确认模型、尺寸、输出数量和费用，再提交批量或高分辨率任务。

bash

curl 'https://ai.tavonilo.com/v1/images/generations' \
  -H "Authorization: Bearer $AI_SHOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<IMAGE_MODEL_ID>",
    "prompt": "A minimal product illustration on a white background",
    "size": "1024x1024"
  }'

TIP

<IMAGE_MODEL_ID> 是占位符。调用前必须以目标 Key 的 /v1/models 返回为准；没有返回的模型、尺寸或参数不应被当作可用能力。

生成、编辑与异步任务

POST /v1/images/generations 用于直接生成图像。
POST /v1/images/edits 用于客户端和目标模型均支持的编辑请求；它通常需要遵循所用 SDK 的 multipart 文件字段格式。
POST /v1/images/generations/async 与 POST /v1/images/edits/async 在服务端异步图像任务存储启用时提交任务；未启用时返回 404。
GET /v1/images/tasks/{task_id} 查询异步任务状态。

异步接口适合需要排队或较长处理时间的工作流。提交成功不等于图片已经可下载；客户端应保存任务 ID、轮询终态，并在用户取消或网络中断时避免重复提交同一业务任务。

参数与计费

图像模型支持的 size、quality、n、参考图和编辑能力会因模型与上游而异。先从一张、默认尺寸的请求开始验证，再提高输出数量或分辨率。实际费用按请求时模型、尺寸、质量和成功输出计算，并以模型与价格和控制台显示为准。

不要假定图像请求可像纯文本请求一样安全重试：超时或客户端断开时，上游可能已经开始或完成生成。业务系统应为用户任务保存自己的幂等标识和状态，在无法确认请求未提交时先查询任务或用量，而不是自动重复扣费请求。

故障处理

400 / 422：模型、尺寸、文件格式或可选参数不兼容；从最小请求开始移除可选字段。
403：当前 Key 没有图像模型或该路由的权限；检查分组和控制台模型列表。
429：并发、余额、额度或上游限制；采用队列和指数退避，不要并发重放整批任务。
5xx 或超时：保留请求 ID、时间、模型和任务 ID（若已获得），再向客服提交脱敏信息。

更多通用恢复原则参见异步图像任务和错误码与排障。