图像Images
更新时间:2024-04-23
功能介绍
根据用户输入的文本生成图片。
注意事项
-
模型不同,调用SDK时,使用参数不同。请结合具体模型,查看参数使用说明进行调用。
- 默认使用模型,即Stable-Diffusion-XL,调用时无需填写model参数,使用的模型,详情见参数说明。
- 指定支持预置服务的模型,使用model参数指定支持预置服务的模型,详情见参数说明。
- 用户快速部署自行发布的模型服务,需使用参数endpoint,详见请求参数说明。
- 调用文心一格(精调后)相关,需先经过SFT模型训练后发布服务,才能调用对应API,更多内容请参考新手指南-平台使用快速开始。
支持模型列表
支持的模型列表如下,及各模型支持的调用方法说明如下,更多详情见请求参数说明。
模型 | 支持预置服务的模型 (使用model参数) |
用户自行发布的模型服务 (使用endpoint参数) |
---|---|---|
Stable-Diffusion-XL | ✓ | ✓ |
文心一格(精调后) | ✕ | ✓ |
调用示例
默认模型
import os
import qianfan
from PIL import Image
import io
# 使用安全认证AK/SK鉴权,通过环境变量方式初始化;替换下列示例中参数,安全认证Access Key替换your_iam_ak,Secret Key替换your_iam_sk
os.environ["QIANFAN_ACCESS_KEY"] = "your_iam_ak"
os.environ["QIANFAN_SECRET_KEY"] = "your_iam_sk"
t2i = qianfan.Text2Image()
resp = t2i.do(prompt="A Ragdoll cat with a bowtie.", with_decode="base64")
img_data = resp["body"]["data"][0]["image"]
img = Image.open(io.BytesIO(img_data))
img.show(img)
指定支持预置服务的模型
使用model字段,指定千帆平台支持预置服务的模型,调用示例如下。
import os
import qianfan
from PIL import Image
import io
# 使用安全认证AK/SK鉴权,通过环境变量方式初始化;替换下列示例中参数,安全认证Access Key替换your_iam_ak,Secret Key替换your_iam_sk
os.environ["QIANFAN_ACCESS_KEY"] = "your_iam_ak"
os.environ["QIANFAN_SECRET_KEY"] = "your_iam_sk"
t2i = qianfan.Text2Image()
resp = t2i.do(prompt="A Ragdoll cat with a bowtie.", with_decode="base64",model="Stable-Diffusion-XL")
img_data = resp["body"]["data"][0]["image"]
img = Image.open(io.BytesIO(img_data))
img.show(img)
用户自行发布的模型服务
对于用户自行发布的模型服务,如文心一格(精调后),通过使用endpoint进行调用,示例如下。
import os
import qianfan
from PIL import Image
import io
# 使用安全认证AK/SK鉴权,通过环境变量方式初始化;替换下列示例中参数,安全认证Access Key替换your_iam_ak,Secret Key替换your_iam_sk
os.environ["QIANFAN_ACCESS_KEY"] = "your_iam_ak"
os.environ["QIANFAN_SECRET_KEY"] = "your_iam_sk"
t2i = qianfan.Text2Image()
resp = t2i.do(prompt="A Ragdoll cat with a bowtie.", with_decode="base64",endpoint="your_custom_endpoint")
img_data = resp["body"]["data"][0]["image"]
img = Image.open(io.BytesIO(img_data))
img.show(img)
返回示例
QfResponse(code=200,
headers={...},
body={'created': 1111,
'data': [{'b64_image': 'xxxxx',
'image': 'xx',
'index': 1,
'object': 'image'}],
'id': 'as-xxx',
'object': 'image',
'usage': {'prompt_tokens': 28, 'total_tokens': 28}})
参数说明
请求参数
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
prompt | string | 是 | 提示词,即用户希望图片包含的元素。说明: (1)当model值为Stable-Diffusion-XL,长度限制为1024字符,建议中文或者英文单词总数量不超过150个 (2)当调用的模型服务为文心一格(精调后),该字段建议使用中文,效果更佳,长度限制为256字符 |
with_decode | string | 否 | 是否自动decode,如果不指定将返回原始的based64 encoded二进制数据,可选值:base64 |
negative_prompt | string | 否 | 反向提示词,即用户希望图片不包含的元素。说明: (1)当model值为Stable-Diffusion-XL,长度限制为1024字符,建议中文或者英文单词总数量不超过150个 (2)当调用的模型服务为文心一格(精调后),长度限制为256字符 |
size | string | 否 | 生成图片长宽,说明: (1)当model值为Stable-Diffusion-XL,默认值 1024x1024,取值范围如下: · 适用头像: ["768x768", "1024x1024", "1536x1536", "2048x2048"] · 适用文章配图 :["1024x768", "2048x1536"] · 适用海报传单:["768x1024", "1536x2048"] · 适用电脑壁纸:["1024x576", "2048x1152"] · 适用海报传单:["576x1024", "1152x2048"] (2)当使用的模型服务为文心一格(精调后),取值范围如下:["1024x1024", "2048x2048", "1280x720", "720x1280", "2560x1440", "1440x2560", "1152x768", "2304x1536", "1024x768", "2048x1536"] |
n | int | 否 | 生成图片数量,说明: (1)默认值为1 (2)取值范围: · 当model值为Stable-Diffusion-XL,取值范围为1-4 · 当使用的模型服务为文心一格(精调后),取值范围为1-2 (3)单次生成的图片较多及请求较频繁可能导致请求超时 |
steps | int | 否 | 迭代轮次,说明: · 默认值为20 · 取值范围为10-50 |
sampler_index | string | 否 | 采样方式,说明: (1)当model值为Stable-Diffusion-XL,默认值:Euler a,可选值如下: · Euler · Euler a · DPM++ 2M · DPM++ 2M Karras · LMS Karras · DPM++ SDE · DPM++ SDE Karras · DPM2 a Karras · Heun · DPM++ 2M SDE · DPM++ 2M SDE Karras · DPM2 · DPM2 Karras · DPM2 a · LMS (2)当使用的模型服务文心一格(精调后),默认值ddim,可选值如下:pndm, · euler_ancestral · dpm-solver · ddim |
model | string | 否 | 模型名称,说明: (1)此参数不填,默认为Stable-Diffusion-XL (2)如果填写,支持模型如下:Stable-Diffusion-XL |
endpoint | string | 否 | 用于指定用户自行发布的模型服务,说明: (1)如果调用文心一格(精调后),endpoint字段为必填 (2)该字段值可以通过查看服务地址获取,详情请查看新手指南-平台使用快速开始: 在创建服务页面,选择模型后,API地址会自动新增个后缀。例如选择模型后,输入API地址为“test1”,endpoint的取值即为“ngxxxol8_test1”,如下图所示, |
retry_count | int | 否 | 重试次数,默认1次 |
request_timeout | float | 否 | 请求超时时间,默认60秒 |
backoff_factor | float | 否 | 请求重试参数,用于指定重试的策略,默认为0 |
seed | integer | 否 | 随机种子,说明: · 不设置时,自动生成随机数 · 取值范围 [0, 4294967295] |
cfg_scale | float | 否 | 提示词相关性,说明:默认值为5,取值范围0-30 |
style | string | 否 | 生成风格。说明: (1)当model值为Stable-Diffusion-XL,默认值为Base,可选值: · Base:基础风格 · 3D Model:3D模型 · Analog Film:模拟胶片 · Anime:动漫 · Cinematic:电影 · Comic Book:漫画 · Craft Clay:工艺黏土 · Digital Art:数字艺术 · Enhance:增强 · Fantasy Art:幻想艺术 · Isometric:等距风格 · Line Art:线条艺术 · Lowpoly:低多边形 · Neonpunk:霓虹朋克 · Origami:折纸 · Photographic:摄影 · Pixel Art:像素艺术 · Texture:纹理 (2)当使用的模型服务文心一格(精调后),默认None |
user_id | string | 否 | 表示最终用户的唯一标识符 |
响应参数
名称 | 类型 | 描述 |
---|---|---|
id | string | 请求的id |
object | string | 回包类型。image:图像生成返回 |
created | int | 时间戳 |
data | list(image_data) | 生成图片结果 |
usage | usage | token统计信息,token数 = 汉字数+单词数*1.3 (仅为估算逻辑) |
image_data说明
名称 | 类型 | 描述 |
---|---|---|
object | string | 固定值"image" |
b64_image | string | 图片base64编码内容 |
image | string | 图片解码后数据,可以直接使用,仅传入with_decode="base64"时候会返回 |
index | int | 序号 |
usage说明
名称 | 类型 | 描述 |
---|---|---|
prompt_tokens | int | 问题tokens数,包含提示词和负向提示词 |
total_tokens | int | tokens总数 |