curl --request GET \
--url https://api.aihubmax.com/v1/tasks/{task_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.aihubmax.com/v1/tasks/{task_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.aihubmax.com/v1/tasks/{task_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.aihubmax.com/v1/tasks/{task_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.aihubmax.com/v1/tasks/{task_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.aihubmax.com/v1/tasks/{task_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aihubmax.com/v1/tasks/{task_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "task-unified-1757165031-uyujaw3d",
"object": "video.generation.task",
"type": "video",
"model": "lipsync-2",
"status": "pending",
"progress": 0,
"created": 1757165031,
"results": null,
"error": null,
"usage": {
"credits_reserved": 5,
"user_group": "default"
}
}查询任务状态
- 查询异步任务的当前状态和结果
- 任务状态流转:
pending→processing→completed/failed;只有completed、failed表示任务结束 - 适用的异步任务处理超过30分钟时,
error可能返回task_delayed状态提示;status仍为processing,请继续查询。progress=100或error非空不表示任务结束 - 处理期限以本任务提示为准;未确认退款时不会显示已退款。适用任务已确认预扣退回时,会在延期提示或失败说明中注明
- 可选传入
sync_upstream=true,对仍在执行中的任务先主动刷新一次最新状态;延期提示本身不改变状态或执行退款 - 任务完成后,结果链接有效期为24小时,请尽快保存
curl --request GET \
--url https://api.aihubmax.com/v1/tasks/{task_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.aihubmax.com/v1/tasks/{task_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.aihubmax.com/v1/tasks/{task_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.aihubmax.com/v1/tasks/{task_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.aihubmax.com/v1/tasks/{task_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.aihubmax.com/v1/tasks/{task_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.aihubmax.com/v1/tasks/{task_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "task-unified-1757165031-uyujaw3d",
"object": "video.generation.task",
"type": "video",
"model": "lipsync-2",
"status": "pending",
"progress": 0,
"created": 1757165031,
"results": null,
"error": null,
"usage": {
"credits_reserved": 5,
"user_group": "default"
}
}任务状态与延期提示
只按status 判断任务是否结束。 progress=100 或 error 非空都不表示任务已经结束。
status | 是否结束 | error |
|---|---|---|
pending | 否,继续查询 | null |
processing | 否,继续查询 | 通常为 null;处理时间较长时可能包含 task_delayed 提示 |
completed | 是,读取 results | null |
failed | 是,读取失败说明 | 包含公共错误码及说明 |
error 字段返回 code=task_delayed、type=task_status。提示写明本任务的实际处理期限;不同任务的期限可能不同,不要把示例中的 2 小时作为固定值。
例如,本次处理期限为 2 小时,且预扣额度尚未退回:
{
"status": "processing",
"progress": 100,
"results": null,
"error": {
"code": "task_delayed",
"type": "task_status",
"message": "任务处理已超过30分钟。若从开始处理起累计满2小时仍未结束,系统将按超时失败处理。届时将自动退还预扣额度。"
}
}
status 仍为 processing,提示会改为等待系统按超时失败处理。这不表示已经退款,请继续查询。
上述 Gateway 视频、图片、音频和文档任务的退款说明只描述本任务的预扣额度:未预扣时说明无需退款;确认预扣已退回后才说明已退回,不再承诺重复退还。失败任务的退款说明追加在 error.message 中,保留原有公共 error.code 和 error.type。usage.credits_reserved 记录原有预扣额度,退款后仍可为正数,不能用它判断是否未退款。
延期提示本身不修改任务状态或执行退款。sync_upstream=true 仍可按接口说明主动刷新一次任务状态。错误码含义见错误码参考。
results 字段格式说明
任务完成(status=completed)后,results 是一个数组,结构按模型不同而异。解析结果前请先根据响应中的 model 字段判定结构类型。
通用格式(大多数模型)
按任务输出类型(type)分组:
type | results[i] 结构 | 典型场景 |
|---|---|---|
image | {url} | 图片生成、编辑、增强 |
video | {url} | 视频生成、对口型、视频编辑 |
audio(TTS / 音乐) | {url} | 语音合成、音乐生成 |
llm | 完整 OpenAI ChatCompletion:{id, object:"chat.completion", created, model, choices[].message, usage} | LLM 生成(llm_router / llm_async) |
上表通用格式的 url 有效期为 24 小时,请尽快保存。特殊格式的链接保留期如有差异,以对应模型说明为准。
特殊格式(按 model 区分)
以下模型的 results[i] 结构不遵循上表通用格式。调用方必须按 model 单独处理。
GPT Image 2.5 生成元数据
model | type | results[i] 结构 | 说明 |
|---|---|---|---|
gpt-image-2.5-flare | image | {url, image_metadata, response_metadata} | url 是本系统保存后的图片地址;逐图片与本次生成公共信息分别保留,不返回 usage |
gpt-image-2.5-sunburst | image | 同 Flare | 每张图的实际尺寸读取 image_metadata.size;此次实测请求 1024x1024,结果为 1254x1254 |
image_metadata 保存图片自身的字段,例如 generation_id、model、size。response_metadata 保存一次生成响应的公共字段,例如 created、background、output_format、quality、size;多张结果中的这部分信息来自同一次请求,不能视作每张图的独立用量。未列举的生成元数据也会保留,调用方应允许新增字段。
下面是结构示例,files.example.com 代表系统返回的文件地址,不是可下载的实测链接:
{
"url": "https://files.example.com/generated/image.png",
"image_metadata": {
"generation_id": "example-generation-id",
"model": "gpt-image-2.5-flare",
"size": "1374x1145"
},
"response_metadata": {
"created": 1789494958,
"background": "opaque",
"output_format": "png",
"quality": "low",
"size": "1374x1145"
}
}
usage。这些图片的保留期由本系统文件存储策略决定,请在任务完成后及时下载保存。
档案创建类(不返回媒体 URL)
model | type | results[i] 结构 | 说明 |
|---|---|---|---|
kling-video-create-voice | video | {voice_id} | 创建可复用的语音档案 ID,供后续 Kling 对口型 / 合成任务引用 |
sora-2-character | video | {character_id, name} | 从参考视频提取角色档案,供后续 Sora 2 任务实现角色一致性 |
phota-create-profile | image | {result_type, profile_id} | 训练人物档案,供其他 PHOTA 模型引用;result_type 固定为 profile |
声音克隆类
model | type | results[i] 结构 | 说明 |
|---|---|---|---|
minimax-voice-clone | audio | {voice_id},带预览文本时附加 {url, content_type} | MiniMax 声音克隆:提交参考音频生成可复用的声音 ID;若请求带了预览文本,额外返回预览音频 url |
语音转写类(不返回媒体 URL)
model | type | results[i] 结构 | 说明 |
|---|---|---|---|
scribe-v2 | audio | {text, language_code, language_probability, words[]} | 语音转文本。words[] 为字级时间戳数组,每项含 text / start / end / type |
视频带种子值
model | type | results[i] 结构 | 说明 |
|---|---|---|---|
seedance-2.0-text-to-video | video | {url, seed} | 额外返回生成种子,用于复现 |
seedance-2.0-fast-text-to-video | video | {url, seed} | 同上 |
seedance-2.0-image-to-video | video | {url, seed} | 同上 |
seedance-2.0-fast-image-to-video | video | {url, seed} | 同上 |
seedance-2.0-reference-to-video | video | {url, seed} | 同上 |
seedance-2.0-fast-reference-to-video | video | {url, seed} | 同上 |
seed 字段始终存在:当生成过程回传了种子时为对应整数;若本次生成未回传种子,则为 null。请按「字段始终存在、值可能为 null」处理。Seedance 2.5(HongniaoAI)
model | type | results[i] 结构 | 说明 |
|---|---|---|---|
seedance-2.5-text-to-video | video | {url, result, id, model, status, progress, created_at, aspectRatio, seconds, completed_at?, processing_time?, video_url?, videoUrl?, video_urls?, videoUrls?, resultUrls?, outputs?, output?, format?, duration?, expires_at?, thumbnail_url?, ...} | url 是 Gateway 统一主视频 URL;result 保留鸿鸟上游完整嵌套结果,顶层与嵌套视频 URL、格式、时长和处理元数据会同时保留。 |
seedance-2.5-image-to-video | video | 同上 | image_url 会被转换为上游 images,结果结构与文生视频相同。 |
seedance-2.5-reference-to-video | video | 同上 | image_urls、video_urls、audio_urls 会被转换为上游 images、videos、audios,结果结构与其他两个 mode 相同。 |
result.output.outputUrls、result.outputs、result.videoUrl、result.videoUrls、result.video_url、result.resultUrls 等字段来自上游任务响应;适配器会把这些字段保留在 results[i].result 中,并将可读取的字段展开到 results[i]。seconds 在鸿鸟任务响应中实测可能是字符串,即使提交请求使用的是整数;调用方应按实际 JSON 类型解析。expires_at、thumbnail_url 以及上游未来新增字段可能缺省,解析器应允许缺失和新增字段。
参考视频快速版降级提示(degraded_reason)
model | type | results[i] 结构 | 说明 |
|---|---|---|---|
seedance-2.0-fast-reference-to-video | video | {url, degraded_reason?} | 当请求的媒体组合为「图+音」或「视频+音」时,快速版无对应模型,系统自动降级到标准参考视频模型,并在 results[0].degraded_reason 注入说明文本。其余媒体组合不含该字段。 |
PBR 材质类(单任务返回多个带语义标签的结果)
model | type | results[i] 结构 | 说明 |
|---|---|---|---|
patina-pbr-maps | image | {url, content_type, result_type: "pbr_map", map_type} | PBR 贴图生成。map_type 标识贴图类型(如 albedo / normal / roughness 等) |
patina-material | image | 混合两种:{url, content_type, result_type: "texture"} 与 {url, content_type, result_type: "pbr_map", map_type} | 同时输出平铺纹理和多张 PBR 贴图;按 result_type 区分 |
patina-material-extract | image | 同 patina-material | 从现有图提取纹理生成 PBR 贴图组 |
音乐生成带歌词文本
model | type | results[i] 结构 | 说明 |
|---|---|---|---|
lyria-3 | audio | {url},部分候选附加 {lyrics} | 30 秒音乐片段;lyrics 为生成的歌词 / 段落结构文本,仅部分候选返回,缺省时不含该字段 |
lyria-3-pro | audio | {url},部分候选附加 {lyrics} | 完整歌曲(最长约 3 分钟);同上,lyrics 按候选不同可能缺省 |
文档转换类(结果为 ZIP 压缩包 URL,非媒体直链)
model | type | results[i] 结构 | 说明 |
|---|---|---|---|
doc2x-v3 | document | {url} | PDF 转换结果。url 指向一个可下载的 ZIP 压缩包,内含转换后的文档文件(md / tex / docx)及图片资源;与 image/video 的直接媒体 URL 不同,此 URL 需解压后使用 |
解析建议
- 先读
model,再解析results:同一type下不同model的结构可能完全不同 - URL 类结果注意过期:通用格式的
url有效期为 24 小时;GPT Image 2.5 按上文文件存储策略保留。业务侧应在收到结果后立即下载转存 - 档案类任务返回的
voice_id/character_id/profile_id是长期有效的资源标识,可直接用于后续任务参数
授权
所有接口均需要使用Bearer Token进行认证
使用时在请求头中添加:
Authorization: Bearer YOUR_API_KEY
路径参数
任务ID,由提交任务接口返回
"task-unified-1757165031-uyujaw3d"
查询参数
是否在返回前主动刷新一次任务状态。仅对仍在执行且已有关联远端任务的记录生效;否则直接返回当前任务状态。
true
响应
查询成功
任务ID
"task-unified-1757165031-uyujaw3d"
任务的具体类型
video.generation.task, image.generation.task, audio.generation.task, llm.generation.task "video.generation.task"
任务的输出类型
video, image, audio, llm "video"
实际使用的模型名称
"lipsync-2"
任务状态。仅以此字段判断任务是否结束;progress=100 或 error 非空不能代替状态判断。
可选值:
| 值 | 含义 | 是否结束 |
|---|---|---|
pending | 等待处理 | 否 |
processing | 处理中,可能附延期提示 | 否 |
completed | 已完成 | 是 |
failed | 已失败 | 是 |
pending, processing, completed, failed "pending"
任务进度百分比
0 <= x <= 1000
任务创建时间戳(Unix 秒)
1757165031
任务结果列表,仅在 status=completed 时有值。
结构按任务输出类型(type)不同:
type | results[i] 结构 | 典型场景 |
|---|---|---|
image | {url},部分模型附带 content_type;特殊任务(如 PHOTA 创建档案)为 {result_type, profile_id} | 图片生成、编辑、增强 |
video | {url},部分模型附带 content_type / seed;特殊子任务(Kling 创建语音 / Sora 2 角色档案)为 {voice_id} 或 {character_id, name} | 视频生成、对口型 |
audio(TTS / 音乐) | {url} | 语音合成、音乐生成 |
audio(STT / 转写) | {text, language_code, language_probability, words[]}(不含 url) | 语音转写(如 Scribe V2) |
audio(声音克隆) | {voice_id},带预览文本时附加 {url, content_type} | 声音克隆(如 MiniMax Voice Clone) |
llm | 完整 OpenAI ChatCompletion:{id, object:"chat.completion", created, model, choices[].message, usage} | LLM 生成(llm_gateway / llm_async) |
通用说明:
- 结果中的 URL 有效期为 24 小时,请尽快保存
type=llm的结果是对话响应,不产生 URL- 部分任务是"非媒体产物"(创建语音档案 / 角色档案等),
results不含url而是 id 类字段
图片结果(type=image)。多数图片模型只返回 url;少数模型(Patina 家族)会附带 content_type;PHOTA 创建档案类任务返回 {result_type, profile_id}(非图片产物)
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
Show child attributes
Show child attributes
失败信息或处理中任务的延期提示,可为空。status=failed 时返回安全错误说明;部分已提交的异步任务处理超过30分钟且仍为 processing 时,返回 code=task_delayed、type=task_status,并说明本任务的实际处理期限。超过期限但尚未终结时会提示等待系统处理,不代表已失败或已退款。延期提示中,未预扣额度时说明无需退款;已确认预扣退回时才说明已退回,不重复承诺退款。Gateway 视频、图片、音频和文档任务失败后的退款说明只追加到 message,保留原有公共 code/type;成功时为 null。是否结束始终以 status 为准。
Show child attributes
Show child attributes
计费信息
Show child attributes
Show child attributes