MaaS_GP_image

请求协议

http

Header

参数名	类型	描述
anthorization	string	鉴权

能力地图

能力	Image Generation	Image Edit
文生图	✓	-
图片编辑	-	✓
多图输入	-	✓ (最多16张)
遮罩编辑	-	✓
流式输出	✓	✓
多种输出格式	✓	✓

一、接口及请求参数

图片生成接口 (Image Generation)

POST
https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/images/generations

根据文本提示词生成图片。

请求参数

属性名	类型	是否必需	描述
prompt	string	是	描述期望图片的文本提示词。
background	string	否	背景行为。可选值：transparent(透明/image2.0不支持)、opaque(不透明)、auto(自动)。
moderation	string	否	内容审核级别。可选值：low、auto。
n	integer	否	生成的图片数量。默认：1。
output_compression	number	否	jpeg或webp格式输出的压缩级别(0-100)。不支持PNG
output_format	string	否	输出图片格式。可选值：png、jpeg、webp。
quality	string	否	输出图片质量。可选值：low、medium、high、auto。
size	string	否	输出图片尺寸。可选值：auto、1024x1024、1536x1024、1024x1536。
stream	boolean	否	是否流式返回。默认false。设为true开启流式输出。
partial_images	number	否	仅流式可用。流式响应时的部分图片数量(0-3)。
user	string	否	终端用户唯一标识符，用于监控和检测滥用。

请求示例

curl -X POST https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
  "prompt": "A beautiful sunset over mountains with vibrant colors",
  "model": "gpt-image-1",
  "quality": "high",
  "size": "1024x1024",
  "n": 1
}'

透明背景示例（image2.0不支持）

curl -X POST https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
  "prompt": "A cute cat sitting, isolated on transparent background",
  "model": "gpt-image-1",
  "background": "transparent",
  "output_format": "png"
}'

流式输出示例

curl -X POST https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
  "prompt": "A futuristic cityscape at night",
  "model": "gpt-image-1",
  "stream": true,
  "partial_images": 2
}'

图片编辑接口 (Image Edit)

POST https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/images/edits

根据提示词编辑或扩展现有图片。

请求参数

属性名	类型	是否必需	描述
image	file	是	上传文件。文件格式需要为jpg或者png，文件不超过50MB
prompt	string	是	描述期望图片编辑效果的文本提示词。
input_fidelity	string	否	对原始输入图片的保真度。可选值：high、low。
mask	string	否	遮罩图片引用，用于指定编辑区域。PNG, 不超过4MB。
model	string	否	使用的模型。
n	number	否	生成的编辑图片数量。
partial_images	number	否	仅流式可用。流式响应时的部分图片数量(0-3)。设为0时单个事件返回完整图片。
quality	string	否	输出质量。可选值：low、medium、high、auto。
size	string	否	输出尺寸。可选值：auto、1024x1024、1536x1024、1024x1536。
stream	boolean	否	是否流式返回。默认false。设为true开启流式输出。
user	string	否	终端用户唯一标识符。

请求示例

{
curl 
--location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/images/edits' \
--header 'Authorization: Bearer $API_KEY' \
--form 'image[]=@"F:\\projects\\AiModels\\images\\1111111111111.png"' \
--form 'prompt="将人物缩减为2个"'
}

二、响应格式

非流式响应

响应示例

{
  "created": 1709312456,
  "background": "opaque",
  "output_format": "png",
  "quality": "high",
  "size": "1024x1024",
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 1250,
    "input_tokens_details": {
      "image_tokens": 1100,
      "text_tokens": 150
    },
    "output_tokens": 4096,
    "output_tokens_details": {
      "image_tokens": 4000,
      "text_tokens": 96
    },
    "total_tokens": 5346
  }
}

响应字段说明

字段	类型	说明
created	number	图片创建的Unix时间戳（秒）
background	string	使用的背景参数。可选值：transparent、opaque
output_format	string	输出格式。可选值：png、webp、jpeg
quality	string	生成图片的质量。可选值：low、medium、high
size	string	生成图片的尺寸
data	array	生成的图片列表
data[].b64_json	string	Base64编码的图片数据
usage	object	Token使用信息
usage.input_tokens	number	输入Token数（图片+文本）
usage.input_tokens_details	object	输入Token明细
usage.output_tokens	number	输出Token数
usage.output_tokens_details	object	输出Token明细
usage.total_tokens	number	总Token数

流式响应

响应示例

event: {operation_type}.partial_image
data: {
  "type": "{operation_type}.partial_image",
  "partial_image_index": 0,
  "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
}

event: {operation_type}.partial_image
data: {
  "type": "{operation_type}.partial_image",
  "partial_image_index": 1,
  "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
}

event: {operation_type}.completed
data: {
  "type": "{operation_type}.completed",
  "created": 1709312456,
  "usage": {
    "input_tokens": 1250,
    "output_tokens": 4096,
    "total_tokens": 5346
  }
}
data: [DONE]

流式响应事件说明

事件类型	说明
{operation_type}.partial_image	返回部分渲染的图片。partial_image_index表示当前是第几个部分图片（从0开始）。部分图片数量由请求参数partial_images控制（0-3）。
{operation_type}.completed	所有图片生成完成，返回最终的usage信息。这是流式响应的最后一个事件。

{operation_type}的值根据请求接口的不同可以是：

image_generation: /images/generations

image_edit: /images/edits

流式参数说明

• stream: true - 开启流式输出模式

• partial_images: 0-3 - 控制返回的部分图片数量

• 0: 不返回部分图片，直接返回完整图片

• 1-3: 返回1-3张渐进式渲染的部分图片，然后返回完整图片

注意事项

• 完整图片可能在所有部分图片返回之前就生成完成

三、错误响应

错误响应示例

{
  "error": {
    "code": "invalid_api_key",
    "message": "Incorrect API key provided",
    "type": "invalid_request_error"
  }
}

常见错误码

错误码	说明
invalid_api_key	API密钥无效
invalid_request_error	请求参数错误
rate_limit_exceeded	超出速率限制
content_policy_violation	内容违反政策
server_error	服务器内部错误

四、附表

	Image-2	Image-1.5	Image-1	Image-1-Mini
优势	最适合高分辨率和 4K 生成、改进的图像编辑和广泛的纵横比支持	最佳选择：现实主义、指令遵循、多模态上下文，以及提升了的速度和成本。	最适合现实主义、执行指令和多模态上下文	最适合快速原型制作、批量生成或成本敏感的用例
输入/输出形式和格式	接受 文本 + 图像 输入;仅输出 base64 中的图像（无 URL 选项）。
图像大小/分辨率	任意分辨率：两个边缘必须是 16 像素的倍数;长边缘高达 3,840 像素 （4K）：纵横比高达 3：1;像素计数 655,360–8,294,400	1024×1024、1024×1536、1536×1024
质量选项	改进后的质量控制：low、medium、high；low针对延迟敏感的用例进行了优化	low medium 、high（默认值 = 高）	low medium 、high（默认值 = 高）	low、（ mediumhigh 默认值 = 中等）
每个请求的图像数	每个请求 1-10 个图像（n 参数）	每个请求 1-10 个图像（n 参数）	每个请求 1-10 个图像（n 参数）	每个请求 1-10 个图像（n 参数）
编辑（剪写/变体）	✅ 改进了使用内绘和变体的编辑性能	✅ 支持掩码和变体 + 提示	✅ 支持通过掩码和提示进行图像修补及变体生成	✅ 支持通过掩码和提示进行修复和变体
人脸保留	✅先进的人脸保真，确保真实且一致的结果	✅用于实现真实且一致效果的高级人脸保真	✅用于逼真、一致结果的高级人脸保真	❌ 没有专门的人脸保留；更适合非人像/普通创意图像
性能与成本	高保真、 现实主义优化 模型;更高的延迟和成本	高保真、 现实主义优化 模型;改进了 GPT-Image-1 的效率和延迟	高保真、 现实主义优化 模型;更高的延迟和成本	大规模或迭代生成的成本高效且更快