文档
快速开始

千象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-Typestringapplication/json 回调以json方式返回结果

请求体将会包含如下内容

参数类型说明
task_idstring任务的task_id
sub_task_resultslist每个子任务的生成结果,详见各接口

温馨提示:

在使用千象API 时,请留意以下几点:

  1. 生成的内容需遵守法律法规,尊重版权,避免侵犯他人知识产权或传播不当信息。
  2. 根据您的积分,API调用次数可能有限。请合理规划使用,以免超出限制。
  3. 在提交请求前,仔细核对文本描述、风格等参数,以确保生成结果符合您的预期。
  4. 如遇到问题,欢迎联系我们的技术支持团队,我们将提供必要的帮助。

基本流程

以文生图为例

获取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),上面标识着成功/失败的信息,参见下表:

错误码错误信息(英文)错误信息(中文)解决方法
0Success请求成功-
1015Invalid Image Format, must be jpg/jpeg/png/webp无效的图片格式,必须为jpg/jpeg/png/webp上传指定格式的图片
1020Invalid image position无效的图片位置-
1022Invalid Aspect Ratio无效宽高比从文档参数说明中选择合适的宽高比
1023Invalid Image Count, Must be 1-4无效的图像数量,必须是1-4重新指定生成的图片数量
1028Please try again after changing the prompt请您更换咒语后再试试吧!更换符合法律、道德规范的prompt
1029The prompt exceeds length limit, please keep it within 1000 characters您提供的提示词超过了最大限制,请保持在1000个字符以内减少提示词数量
1030The negative prompt exceeds length limit, please keep it within 1000 characters您提供的负向提示词超过了最大限制,请保持在1000个字符以内减少负向提示词数量
1037Missing necessary parameter缺少必要参数检查遗漏的必要参数(参考相关接口的参数说明)
1038Invalid parameter type无效的参数类型更换有效类型的参数
1039Input parameter has None/Null value输入参数有None/Null值提供非空参数
1040Required parameter cannot be empty string必选参数不能为空字符串提供非空字符串作为参数
1043Invalid base64 format无效的base64格式检查并提供有效的base64格式数据
1044Video size exceeded, must no more than 100MB视频大小超出限制,不能大于100MB减小视频文件的大小,确保不超过100MB
1050Please try again after changing the image请您更换图片后再试试更换图片后重试
1051Invalid Resolution无效的分辨率更换分辨率参数
1052Invalid Algo Version无效的模型版本更换模型版本
1053Invalid Upscale Ratio无效的增强倍数更换增强倍数
1054Invalid Language Type无效的语言类型更换语言类型
1055Invalid parameter choice无效的参数取值更换不支持的参数
2002Not support the module不支持的模型类型选择支持的模型类型
2019User authentication error用户鉴权失败检查请求头中的token,并与用户中心的token进行比对
3020Exceeded User Request Limit, Please Try Again Later您在单位时间内的请求数量已超出限制,请稍后再试稍后片刻
3021Requests Overload, Please Try Again Later系统当前使用人数较多,请稍后再试静待系统恢复
3022Exceeded Maximum Parallel Number Limit for Running Tasks, Please Try Again Later超出运行中任务的最大并行数量限制,请稍后再试稍候片刻,等待任务完成

返回语言

在请求中我们支持返回中文和英文两种模型的错误信息,只需要在请求头中添加"X-accept-language"即可控制语言的切换(建议使用英文)。

Header

参数类型是否必填说明
X-accept-languagestring默认返回为中文信息,当前支持值["zh", "en"],其中"zh"代表返回中文信息,"en"代表返回英文信息