查询任务状态

curl --request GET \
  --url https://api.foxapi.cc/v1/tasks/{task_id} \
  --header 'Authorization: Bearer <token>'

{
  "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"
  }
}

GET

tasks

{task_id}

查询任务状态

curl --request GET \
  --url https://api.foxapi.cc/v1/tasks/{task_id} \
  --header 'Authorization: Bearer <token>'

{
  "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"
  }
}

`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 单独处理。

档案创建类（不返回媒体 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」处理。

参考视频快速版降级提示（`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 小时，业务侧应在收到结果后立即下载转存
档案类任务返回的 voice_id / character_id / profile_id 是长期有效的资源标识，可直接用于后续任务参数

授权

Authorization

string

header

必填

所有接口均需要使用Bearer Token进行认证

使用时在请求头中添加：

Authorization: Bearer YOUR_API_KEY

路径参数

task_id

string

必填

任务ID，由提交任务接口返回

示例:

"task-unified-1757165031-uyujaw3d"

查询参数

sync_upstream

boolean

默认值:false

是否在返回前主动刷新一次任务状态。仅对仍在执行且已有关联远端任务的记录生效；否则直接返回当前任务状态。

示例:

true

响应

查询成功

string

任务ID

示例:

"task-unified-1757165031-uyujaw3d"

object

enum<string>

任务的具体类型

可用选项:

video.generation.task,

image.generation.task,

audio.generation.task,

llm.generation.task

示例:

"video.generation.task"

type

enum<string>

任务的输出类型

可用选项:

video,

image,

audio,

llm

示例:

"video"

model

string

实际使用的模型名称

示例:

"lipsync-2"

status

enum<string>

任务状态

可选值：

值	含义
`pending`	等待处理
`processing`	处理中
`completed`	已完成
`failed`	已失败

可用选项:

pending,

processing,

completed,

failed

示例:

"pending"

progress

integer

任务进度百分比

必填范围: 0 <= x <= 100

示例:

0

created

integer

任务创建时间戳（Unix 秒）

示例:

1757165031

results

object[] | null

任务结果列表，仅在 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}（非图片产物）

Show child attributes

error

object

错误信息，仅在 status=failed 时有值

Show child attributes

usage

object

计费信息

Show child attributes

Doc2X V3 PDF 转换错误码参考

​results 字段格式说明

​通用格式（大多数模型）

​特殊格式（按 model 区分）

​档案创建类（不返回媒体 URL）

​声音克隆类

​语音转写类（不返回媒体 URL）

​视频带种子值

​参考视频快速版降级提示（degraded_reason）

​PBR 材质类（单任务返回多个带语义标签的结果）

​音乐生成带歌词文本

​文档转换类（结果为 ZIP 压缩包 URL，非媒体直链）

​解析建议

授权

所有接口均需要使用Bearer Token进行认证

路径参数

查询参数

响应

`results` 字段格式说明

通用格式（大多数模型）

特殊格式（按 `model` 区分）

档案创建类（不返回媒体 URL）

声音克隆类

语音转写类（不返回媒体 URL）

视频带种子值

参考视频快速版降级提示（`degraded_reason`）

PBR 材质类（单任务返回多个带语义标签的结果）

音乐生成带歌词文本

文档转换类（结果为 ZIP 压缩包 URL，非媒体直链）

解析建议