图像 API
文生图与图生图/编辑，同步返回图片 URL 或 Base64 数据
图像接口提供文生图与图生图/编辑能力，均为同步请求，成功后直接返回图片 URL 或 Base64 数据。
接口一览
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /v1/images/generations | 文生图 |
| POST | /v1/images/edits | 图生图 / 图像编辑 |
前置条件：model 须为 模型 API 中 supported_endpoint_types 含 image-generation 的模型。
计费：按次计费，响应 usage 字段见 公共响应对象。
POST /v1/images/generations
文生图。
鉴权：Bearer Token
Content-Type：application/json
请求体
{
"model": "dall-e-3",
"prompt": "A white siamese cat sitting on a windowsill, watercolor style",
"n": 1,
"size": "1024x1024",
"quality": "standard",
"response_format": "url"
}
请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 图像模型 ID |
prompt | string | 是 | 图像描述 |
n | integer | 否 | 生成数量，默认 1 |
size | string | 否 | 尺寸，如 1024x1024、1792x1024 |
quality | string | 否 | 画质，如 standard、hd |
response_format | string | 否 | url（默认）或 b64_json |
style | string | 否 | 风格，如 vivid、natural |
Agnes 图像模型示例（含参考图）：
{
"model": "agnes-image-2.0-flash",
"prompt": "A sunset over the ocean, cinematic lighting",
"size": "1024x768",
"response_format": "url",
"extra_body": {
"response_format": "url"
},
"image": ["https://example.com/reference.jpg"]
}
请求示例（curl）
curl https://www.yunsell.com/v1/images/generations \
-H "Authorization: Bearer sk-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "dall-e-3",
"prompt": "A white siamese cat sitting on a windowsill, watercolor style",
"n": 1,
"size": "1024x1024",
"quality": "standard",
"response_format": "url"
}'
响应体
HTTP 200
{
"created": 1712697600,
"data": [
{
"url": "https://cdn.example.com/generated/image_abc123.png",
"revised_prompt": "A white Siamese cat perched on a sunlit windowsill, rendered in soft watercolor style."
}
],
"usage": {
"quota_type": 1,
"prompt_tokens": 0,
"completion_tokens": 0,
"total_tokens": 0,
"request_count": 1,
"quota": 5000
}
}
response_format 为 b64_json 时：
{
"created": 1712697600,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
}
]
}
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
created | integer | Unix 时间戳（秒） |
data | array | 生成结果，长度等于请求中的 n |
data[].url | string | 图片 URL（response_format=url 时返回） |
data[].b64_json | string | Base64 编码图片（response_format=b64_json 时返回） |
data[].revised_prompt | string | 模型改写后的 prompt（部分模型返回） |
usage | object | 计费信息，见 公共响应对象 |
url与b64_json互斥，取决于请求中的response_format。
失败响应
HTTP 400 等，格式见 标准错误。
POST /v1/images/edits
图生图 / 图像编辑。
鉴权：Bearer Token
Content-Type：multipart/form-data 或 application/json（视模型/渠道支持）
请求体（multipart/form-data）
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 图像模型 |
prompt | string | 是 | 编辑描述 |
image | file | 是 | 待编辑图片 |
mask | file | 否 | 蒙版（局部编辑） |
n | integer | 否 | 生成数量 |
size | string | 否 | 输出尺寸 |
response_format | string | 否 | url 或 b64_json |
请求体（JSON，部分渠道支持 URL 数组）
{
"model": "agnes-image-2.0-flash",
"prompt": "Add a red scarf to the cat",
"size": "1024x768",
"image": ["https://example.com/cat.jpg"],
"response_format": "url"
}
请求示例（curl）
JSON（URL 数组）：
curl https://www.yunsell.com/v1/images/edits \
-H "Authorization: Bearer sk-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "agnes-image-2.0-flash",
"prompt": "Add a red scarf to the cat",
"size": "1024x768",
"image": ["https://example.com/cat.jpg"],
"response_format": "url"
}'
multipart/form-data（上传本地文件）：
curl https://www.yunsell.com/v1/images/edits \
-H "Authorization: Bearer sk-xxx" \
-F "model=dall-e-2" \
-F "prompt=Add a red scarf to the cat" \
-F "image=@/path/to/cat.png" \
-F "response_format=url"
响应体
HTTP 200，结构与 /v1/images/generations 相同：
{
"created": 1712697600,
"data": [
{
"url": "https://cdn.example.com/generated/edit_abc123.png"
}
]
}