Pixeling千象API接口文档

基本概念介绍

接口介绍

HiDream.ai 提供的Pixeling千象API允许开发者和用户请求生成文本、图像和视频内容。该API利用HiDream.ai强大的自研多模态大模型，支持用户通过文本描述或现有图片作为输入，生成全新的视觉内容。API的设计旨在为开发者提供灵活、高效和易于集成的内容生成解决方案。

令牌（token）

token中包含用户的个人信息，如用户名、权益、积分数，token是我们校验用户身份信息的方式，具有高度保密性，需要用户妥善保管。token存在一定的过期时间，过期后需要重新获取。

调用限制

目前Pixeling千象API存在若干种调用限制，调用限制可能会在任何一种中达到，取决于哪个先发生。它们分别是：

(1) 每分钟任务数限制：基于提交的生成任务数，一张图片、一段视频对应为1(如一个请求中包含4张图片生成，则任务数计为4)。对于不同类型的请求，每分钟请求数限制并不同。

(2) 并行请求数限制：基于提交请求的次数，一次生成2张图片算作一次并行请求。请求数有五个等级

(3) 系统请求数限制：当系统过载时，会限制后请求用户的请求，需要您静待系统恢复。

(4) 合法性检验：当请求参数中存在政治敏感、暴力黄色等不合法信息时，系统会将其拦截，请您更换相关信息。

回调

Pixeling千象API支持回调，如果请求参数中notify_url值不为空, 则会在任务完成时以HTTP POST方式调用该回调通知地址, 并根据HTTP返回状态码是否为200判断是否成功, 回调超时时间为5秒, 如果不成功则每隔1秒进行重试, 最多请求次数为3次，具体可见每个接口的请求说明。

请求Header如下

请求体将会包含如下内容

温馨提示：

在使用 Pixeling千象API 时，请留意以下几点：

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

基本流程

以文生图为例

获取token

注册后获取api-key，通过api-key发送get请求来获取token，详情参见接口认证部分。

提交文生图任务

参见接口的具体说明，发送生成任务请求一般需要传递token、具体任务参数、请求头等信息。以下示例为文生图Python代码：

import requests
import json
import uuid

USER_Authorization = <请使用您的token>  # 获取方式详见接口文档https://www.hidreamai.com/docs/pixeling/user/token.html


# 请求头
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,
    "request_id": str(uuid.uuid4())
}

# 发送POST请求
url = 'https://www.hidreamai.com/api-pub/gw/v2/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>  # 获取方式详见接口文档https://www.hidreamai.com/docs/pixeling/user/token.html
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/v2/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之外均为生成失败，参见下表：

错误码

每次发送完请求后会获取到一个json格式的响应，其中包含错误码（code）、信息（message），上面标识着成功/失败的信息，参见下表：

返回语言

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

Header