1 Images接口描述
| 接口名称 |
请求路径 |
功能描述 |
| 图像生成 |
/v1/images/generations |
给定提示和/或输入图像，模型将生成一张新图像 |
| 图像编辑 |
/v1/images/edits |
基于原始图像和提示，创建编辑或扩展的图像 |
| 图像变化 |
/v1/images/variations |
创建给定图像的变化 |
2 请求参数
Images各接口请求参数不同，下面分三个小节分别对这三个接口的请求参数进行说明。
2.1 Image Generation 接口请求参数
2.1.1 请求头参数
| 参数 |
示例值 |
描述 |
| Authorization |
Bearer $OPEN_API_KEY |
填入鉴权Api Key |
| Content-Type |
application/json |
|
2.1.2 请求Body参数
| 参数名称 |
参数类型 |
必选 |
描述 |
| model |
string |
是 |
模型名称，默认dall-e-2。 |
| prompt |
string |
是 |
所需图像的文本描述，最大长度1000（dall-e-2）或 4000（dall-e-3）。 |
| n |
int |
否 |
要生成的图像数。一般取值范围[1, 10]，默认值为1，dall-e-3 n仅能为1。 |
| quality |
string |
否 |
生成图像质量。仅支持dall-e-3。 |
| response_format |
string |
否 |
返回图像的格式。一般取值范围url, b64_json，默认值为b64_json，默认是url。 |
| size |
string |
否 |
输出的图像尺寸（高x宽）。dall-e-2 模型取值范围是：256x256,512x512,1024x1024，默认值为1024x1024，dall-e-3 模型取值范围是：1024x1024,1792x1024,1024x1792。 |
| style |
string |
否 |
生成图像风格。仅支持dall-e-3，一般取值范围vivid, natural。 |
| user |
string |
否 |
用户唯一身份ID。 |
2.2 Image Edit 接口请求参数
2.2.1 请求头参数
| 参数 |
示例值 |
描述 |
| Authorization |
Bearer $OPEN_API_KEY |
填入鉴权Api Key |
| Content-Type |
multipart/form-data |
|
2.2.2 请求Body参数
| 参数名称 |
参数类型 |
必选 |
描述 |
| model |
string |
是 |
模型名称，仅支持dall-e-2。 |
| prompt |
string |
是 |
所需图像的文本描述，最大长度1000（dall-e-2）。 |
| image |
bytes |
是 |
编辑的初始图像。必须是有效的 PNG 文件，小于 4MB，并且尺寸与图片相同。初始图像被编码到潜在空间，并向其中添加噪声。 |
| mask |
bytes |
否 |
附加图片，其完全透明区域（例如 alpha 为零的区域）指示应编辑图片的位置。必须是有效的 PNG 文件，小于 4MB，并且尺寸与图片相同。 |
| n |
int |
否 |
要生成的图像数。一般取值范围[1, 10]，默认值为1。 |
| response_format |
string |
否 |
返回图像的格式。一般取值范围url, b64_json，默认值为b64_json，默认是url。 |
| size |
string |
否 |
输出的图像尺寸（高x宽）。取值范围是：256x256,512x512,1024x1024，默认值为1024x1024。 |
| user |
string |
否 |
用户唯一身份ID。 |
2.3 Image Variation 接口请求参数
2.3.1 请求头参数
| 参数 |
示例值 |
描述 |
| Authorization |
Bearer $OPEN_API_KEY |
填入鉴权Api Key |
| Content-Type |
multipart/form-data |
|
2.3.2 请求Body参数
| 参数名称 |
参数类型 |
必选 |
描述 |
| model |
string |
是 |
模型名称，仅支持dall-e-2。 |
| prompt |
string |
是 |
所需图像的文本描述，最大长度1000（dall-e-2）。 |
| image |
bytes |
是 |
编辑的初始图像。必须是有效的 PNG 文件，小于 4MB，并且尺寸与图片相同。初始图像被编码到潜在空间，并向其中添加噪声。 |
| n |
int |
否 |
要生成的图像数。一般取值范围[1, 10]，默认值为1。 |
| response_format |
string |
否 |
返回图像的格式。一般取值范围url, b64_json，默认值为b64_json，默认是url。 |
| size |
string |
否 |
输出的图像尺寸（高x宽）。取值范围是：256x256,512x512,1024x1024，默认值为1024x1024。 |
| user |
string |
否 |
用户唯一身份ID。 |
3 请求返回
Images 所有接口返回参数全部相同，不做区分说明。
3.1 请求正常返回
| 字段名称 |
二级字段 |
字段类型 |
描述 |
| created |
|
string |
Unix时间戳（以秒为单位）。 |
| data |
|
array |
图像列表 |
| - |
b64_json |
string |
b64_json 格式图片 |
| - |
url |
string |
url 格式图片 |
| - |
revised_prompt |
role |
实际使用的修改后的prompt |
返回结果示例
{
"id": "1714459832",
"data": [{
"url": ""
}]
}
3.2 异常返回
异常返回时：
- http code 返回非200。
- http body 中返回 error 结构，error结构中包含code、type、message、param等信息，具体可见OpenAPI接口文档中的error结构描述及错误码部分介绍。
错误结果示例
{
"error": {
"message": "You exceeded your current quota, please check your plan and billing details.",
"type": "rate_limit_error",
"param": null,
"code": "rate_limit_exceeded"
}
}
4 请求示例代码
4.1 Image Generation 请求
4.1.1 curl方式请求
curl --request POST
--url $OPEN_AI_HOST/v1/images/generations
--header 'Accept: */*'
--header 'Accept-Encoding: gzip, deflate, br'
--header 'Authorization: Bearer $OPEN_API_KEY'
--header 'Content-Type: application/json'
--data '{
"model": "dall-e-2",
"prompt": "A cute baby sea otter",
"n": 1,
"size": "1024x1024"
}'
4.1.2 python方式请求
import json
import requests
URL = "$OPEN_AI_HOST/v1/images/gererations"
headers = {
"Authorization": "Bearer $OPEN_API_KEY",
"Content-Type": "application/json"
}
data = {
"model": "dall-e-2",
"prompt" : "A cute baby sea otter",
"n" : 1,
"size" : "512x512"
}
try:
response = requests.post(URL, headers=headers, json=data)
if response.status_code != 200:
print(response.json())
else:
url = response.json()["data"][0]["url"]
except Exception as e:
print(f"Exception: {e}")
4.1.3 openai 客户端示例代码
import openai
from openai import OpenAI
client = OpenAI(base_url="$OPEN_AI_HOST/v1", api_key="$OPEN_API_KEY")
try:
response = client.images.generate(
model="dall-e-2",
prompt="A cute baby sea otter",
)
print(f"{response.data[0].url}")
except openai.APIStatusError as e:
print(f"APIStatusError: {e.status_code}, {e.message}, {e.body}")
except openai.APIError as e:
print(f"APIError: {e.body}")
except Exception as e:
print(f"Exception: {e}")
4.2 Image Edit 请求
4.2.1 curl方式请求
curl --request POST
--url $OPEN_AI_HOST/v1/images/edits
--header 'Accept: */*'
--header 'Accept-Encoding: gzip, deflate, br'
--header 'Authorization: Bearer $OPEN_API_KEY'
--header 'Content-Type: multipart/form-data'
--form model=dall-e-2
--form prompt=A cute baby sea otter
--form 'image=[Object object]'
4.2.2 python方式请求
import json
import requests
URL = "$OPEN_AI_HOST/v1/images/edits"
headers = {
"Authorization": "Bearer $OPEN_API_KEY",
"Content-Type": "multipart/form-data"
}
files = {
"image" : open(image_path, "rb"),
"model" : "dall-e-2",
"prompt" : "A cute baby sea otter"
}
try:
response = requests.post(URL, headers=headers, files=files)
if response.status_code != 200:
print(response.json())
else:
url = response.json()["data"][0]["url"]
except Exception as e:
print(f"Exception: {e}")
4.2.3 openai 客户端示例代码
import openai
from openai import OpenAI
client = OpenAI(base_url="$OPEN_AI_HOST/v1", api_key="$OPEN_API_KEY")
try:
response = client.images.edit(
image=open("otter.png", "rb"),
mask=open("mask.png", "rb"),
model="dall-e-2",
prompt="A cute baby sea otter",
)
print(f"{response.data[0].url}")
except openai.APIStatusError as e:
print(f"APIStatusError: {e.status_code}, {e.message}, {e.body}")
except openai.APIError as e:
print(f"APIError: {e.body}")
except Exception as e:
print(f"Exception: {e}")
4.3 Image Variation 请求
4.3.1 curl方式请求
curl --request POST
--url $OPEN_AI_HOST/v1/images/variations
--header 'Accept: */*'
--header 'Accept-Encoding: gzip, deflate, br'
--header 'Authorization: Bearer $OPEN_API_KEY'
--header 'Content-Type: multipart/form-data'
--form model=dall-e-2
--form prompt=A cute baby sea otter
--form 'image=[Object object]'
4.3.2 python方式请求
import json
import requests
URL = "$OPEN_AI_HOST/v1/images/variations"
headers = {
"Authorization": "Bearer $OPEN_API_KEY",
"Content-Type": "multipart/form-data"
}
files = {
"image" : open(image_path, "rb"),
"model" : "dall-e-2",
"prompt" : "A cute baby sea otter"
}
try:
response = requests.post(URL, headers=headers, files=files)
if response.status_code != 200:
print(response.json())
else:
url = response.json()["data"][0]["url"]
except Exception as e:
print(f"Exception: {e}")
4.3.3 openai 客户端示例代码
import openai
from openai import OpenAI
client = OpenAI(base_url="$OPEN_AI_HOST/v1", api_key="$OPEN_API_KEY")
try:
response = client.images.create_variation(
image=open("image_edit_original.png", "rb"),
model="dall-e-2",
prompt="A cute baby sea otter",
)
print(f"{response.data[0].url}")
except openai.APIStatusError as e:
print(f"APIStatusError: {e.status_code}, {e.message}, {e.body}")
except openai.APIError as e:
print(f"APIError: {e.body}")
except Exception as e:
print(f"Exception: {e}")
