千象API接口文档
基本概念介绍
接口介绍
HiDream.ai提供的千象API允许开发者和用户请求生成文本、图像和视频内容。该API利用HiDream.ai强大的自研多模态大模型,支持用户通过文本描述或现有图片作为输入,生成全新的视觉内容。API的设计旨在为开发者提供灵活、高效和易于集成的内容生成解决方案。
令牌(token)
token是我们校验用户身份信息的方式,具有高度保密性,需要用户妥善保管,请注册 (opens in a new tab)后进入token管理 (opens in a new tab)进行token的查询、新增。
调用限制
目前千象API存在若干种调用限制,调用限制可能会在任何一种中达到,取决于哪个先发生。它们分别是:
(1) 每分钟任务数限制:基于提交的生成任务数,一张图片、一段视频对应为1(如一个请求中包含4张图片生成,则任务数计为4)。对于不同类型的请求,每分钟请求数限制并不同。
请求类型 | 限制数 |
---|---|
文生图、图生图 | 100 |
文生视频、图生视频 | 10 |
矢量图 | 20 |
智能拓图 | 20 |
智能重绘 | 20 |
视频风格化 | 2 |
动漫头像 | 20 |
(2) 并行请求数限制:基于提交请求的次数,一次生成2张图片算作一次并行请求。请求数有五个等级
用户等级 | 限制数 |
---|---|
免费用户 | 1 |
一级会员 | 3 |
二级会员 | 5 |
三级会员 | 7 |
四级会员 | 10 |
(3) 系统请求数限制:当系统过载时,会限制后请求用户的请求,需要您静待系统恢复。
(4) 合法性检验:当请求参数中存在政治敏感、暴力黄色等不合法信息时,系统会将其拦截,请您更换相关信息。
回调
千象API支持回调,如果请求参数中notify_url
值不为空, 则会在任务完成时以HTTP POST
方式调用该回调通知地址, 并根据HTTP
返回状态码是否为200
判断是否成功, 回调超时时间为5秒, 如果不成功则每隔1秒进行重试, 最多请求次数为3次,具体可见每个接口的请求说明。
请求Header如下
参数 | 类型 | 说明 |
---|---|---|
Content-Type | string | application/json 回调以json 方式返回结果 |
请求体将会包含如下内容
参数 | 类型 | 说明 |
---|---|---|
task_id | string | 任务的task_id |
sub_task_results | list | 每个子任务的生成结果,详见各接口 |
温馨提示:
在使用千象API 时,请留意以下几点:
- 生成的内容需遵守法律法规,尊重版权,避免侵犯他人知识产权或传播不当信息。
- 根据您的积分,API调用次数可能有限。请合理规划使用,以免超出限制。
- 在提交请求前,仔细核对文本描述、风格等参数,以确保生成结果符合您的预期。
- 如遇到问题,欢迎联系我们的技术支持团队,我们将提供必要的帮助。
基本流程
以文生图为例
获取token
注册 (opens in a new tab)后获取token (opens in a new tab)。
提交文生图任务
参见接口的具体说明,发送生成任务请求一般需要传递token、具体任务参数、请求头等信息。以下示例为文生图Python代码:
import requests
import json
import uuid
USER_Authorization = <请使用您的token>
# 请求头
headers = {
'Authorization': f'Bearer {USER_Authorization}',
'Content-Type': 'application/json',
'API-User-ID': '' # 可选的用户唯一标识
}
# 请求体参数
data = {
"prompt": "Romantic painting of a ship sailing in a stromy sea, with dramatic lighting and powerful waves", # 必要参数
"negative_prompt": "sun",
"aspect_ratio": "1:1",
"img_count": 1,
"version": "v2",
"resolution": "2048*2048",
"request_id": str(uuid.uuid4())
}
# 发送POST请求
url = 'https://www.hidreamai.com/api-pub/gw/v3/image/txt2img/async'
response = requests.post(url, headers=headers, data=json.dumps(data))
# 处理响应
if response.status_code == 200:
if response.json()['code'] == 0:
task_id = response.json()['result']['task_id']
print(task_id)
else:
print(response.json()['message'])
else:
print(response.status_code)
安装依赖的库后,补充token、请求参数等信息,运行代码,得到一个task_id。
获取文生图结果
参见获取结果接口,发送获取结果请求。一般需要传递token、task_id等信息。
import requests
USER_Authorization = <请使用您的token>
task_id = <请使用上一步返回的task_id> # <task_id>
# 请求头
headers = {
'Authorization': f'Bearer {USER_Authorization}'
}
# 请求参数
params = {
'task_id': task_id,
'request_id': ''
}
# 发送GET请求
url = 'https://www.hidreamai.com/api-pub/gw/v3/image/txt2img/async/results'
response = requests.get(url, headers=headers, params=params)
# 处理响应
if response.status_code == 200:
if response.json()['code'] == 0:
results = response.json()['result']['sub_task_results']
for result in results:
print(f"task_status: {result['task_status']}, task_completion: {result['task_completion']}, image_url: {result['image']}")
else:
print(response.json()['message'])
else:
print(response.status_code)
补充token,填写步骤2中返回的task_id,运行代码,即可得到任务信息(任务状态、任务完成度、任务结果)。
发送获取结果请求后,会返回一个任务状态码(task_status),目前除了0,1,2之外均为生成失败,参见下表:
状态码 | 解释 |
---|---|
0 | 等待中 |
1 | 完成 |
2 | 处理中 |
3 | 失败 |
4 | 结果未通过审核 |
1004、1005、1006 | 算法无生成结果(建议更换prompt) |
错误码
每次发送完请求后会获取到一个json格式的响应,其中包含错误码(code)、信息(message),上面标识着成功/失败的信息,参见下表:
错误码 | 错误信息(英文) | 错误信息(中文) | 解决方法 |
---|---|---|---|
0 | Success | 请求成功 | - |
1015 | Invalid Image Format, must be jpg/jpeg/png/webp | 无效的图片格式,必须为jpg/jpeg/png/webp | 上传指定格式的图片 |
1020 | Invalid image position | 无效的图片位置 | - |
1022 | Invalid Aspect Ratio | 无效宽高比 | 从文档参数说明中选择合适的宽高比 |
1023 | Invalid Image Count, Must be 1-4 | 无效的图像数量,必须是1-4 | 重新指定生成的图片数量 |
1028 | Please try again after changing the prompt | 请您更换咒语后再试试吧! | 更换符合法律、道德规范的prompt |
1029 | The prompt exceeds length limit, please keep it within 1000 characters | 您提供的提示词超过了最大限制,请保持在1000个字符以内 | 减少提示词数量 |
1030 | The negative prompt exceeds length limit, please keep it within 1000 characters | 您提供的负向提示词超过了最大限制,请保持在1000个字符以内 | 减少负向提示词数量 |
1037 | Missing necessary parameter | 缺少必要参数 | 检查遗漏的必要参数(参考相关接口的参数说明) |
1038 | Invalid parameter type | 无效的参数类型 | 更换有效类型的参数 |
1039 | Input parameter has None/Null value | 输入参数有None/Null值 | 提供非空参数 |
1040 | Required parameter cannot be empty string | 必选参数不能为空字符串 | 提供非空字符串作为参数 |
1043 | Invalid base64 format | 无效的base64格式 | 检查并提供有效的base64格式数据 |
1044 | Video size exceeded, must no more than 100MB | 视频大小超出限制,不能大于100MB | 减小视频文件的大小,确保不超过100MB |
1050 | Please try again after changing the image | 请您更换图片后再试试 | 更换图片后重试 |
1051 | Invalid Resolution | 无效的分辨率 | 更换分辨率参数 |
1052 | Invalid Algo Version | 无效的模型版本 | 更换模型版本 |
1053 | Invalid Upscale Ratio | 无效的增强倍数 | 更换增强倍数 |
1054 | Invalid Language Type | 无效的语言类型 | 更换语言类型 |
1055 | Invalid parameter choice | 无效的参数取值 | 更换不支持的参数 |
2002 | Not support the module | 不支持的模型类型 | 选择支持的模型类型 |
2019 | User authentication error | 用户鉴权失败 | 检查请求头中的token,并与用户中心的token进行比对 |
3020 | Exceeded User Request Limit, Please Try Again Later | 您在单位时间内的请求数量已超出限制,请稍后再试 | 稍后片刻 |
3021 | Requests Overload, Please Try Again Later | 系统当前使用人数较多,请稍后再试 | 静待系统恢复 |
3022 | Exceeded Maximum Parallel Number Limit for Running Tasks, Please Try Again Later | 超出运行中任务的最大并行数量限制,请稍后再试 | 稍候片刻,等待任务完成 |
返回语言
在请求中我们支持返回中文和英文两种模型的错误信息,只需要在请求头中添加"X-accept-language"即可控制语言的切换(建议使用英文)。
Header
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
X-accept-language | string | 否 | 默认返回为中文信息,当前支持值["zh", "en"],其中"zh"代表返回中文信息,"en"代表返回英文信息 |