H5Zoom API

Seedance 视频生成接口

使用本站创建的 API 令牌，完成视频任务创建、状态查询和成品下载。

https://newapi.h5zoom.com/v1

快速开始

当前文档适用于 seedance-2.0-0826 和 sd-2-c1。两者使用同一套接口，模型规则请看下方对照。

创建任务

提交提示词、生成时长和画面参数，保存响应中的任务 ID。

轮询状态

按模型建议的时间间隔查询，直到任务完成或失败。

下载视频

任务成功后，通过内容接口获取视频文件。

重要：请在本站后台的“令牌管理”中创建 API Key。请勿在网页、前端代码或公开仓库中暴露你的 Key。

模型区别

两个模型的认证、接口路径、请求结构和素材字段相同。调用时只需在 model 字段选择对应模型，并遵守其单独的任务规则。

模型	请求结构	轮询建议	特别说明
`seedance-2.0-0826`	`input` + `parameters`	每 3-5 秒一次	`parameters.duration` 取值 1-25。
`sd-2-c1`	`input` + `parameters`	每 20 秒以上一次	生成结果请及时保存。含参考视频时，输入视频与输出视频时长合计不超过 25 秒。

注意：同一个任务只传一个模型名。不要把不同模型的时长或能力规则混用。

鉴权方式

所有请求均使用 Bearer Token 鉴权。将 YOUR_API_KEY 替换为你在本站创建的令牌。

HTTP Header

Authorization: Bearer YOUR_API_KEY

POST/videos创建视频任务

GET/videos/{task_id}查询任务状态

GET/videos/{task_id}/content下载已完成视频

创建视频任务

向 POST /videos 发送 JSON 请求。input.prompt 和 parameters.duration 为必填字段。

字段	类型	说明
`model`	string	填写 `seedance-2.0-0826` 或 `sd-2-c1`
`input.prompt`	string	视频提示词，描述主体、动作、环境、镜头和风格
`parameters.duration`	integer	视频时长。`seedance-2.0-0826` 取值 1-25，`sd-2-c1` 请使用渠道支持的时长。
`parameters.resolution`	string	输出分辨率，例如 `720p`
`parameters.ratio`	string	画面比例，例如 `16:9` 或 `9:16`

最小请求示例

cURL

curl --request POST "https://newapi.h5zoom.com/v1/videos" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedance-2.0-0826",
    "input": {
      "prompt": "雨后的城市街道，人物撑伞向前行走，镜头平稳跟拍，写实电影质感"
    },
    "parameters": {
      "duration": 5,
      "resolution": "720p",
      "ratio": "16:9"
    }
  }'

创建成功响应

JSON

{
  "id": "task_xxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2.0-0826",
  "status": "PENDING",
  "progress": 0
}

请保存 id 或 task_id，后续查询和下载都需要使用该值。

调用 sd-2-c1：请求体结构无需改变，只需将示例中的 model 替换为 sd-2-c1。例如 "model": "sd-2-c1"。

使用参考素材

需要图片、视频或音频参考时，在 input.media 中加入素材。素材 URL 必须是服务器可直接访问的公网 HTTPS 地址。

type	用途
`first_frame`	首帧图片
`last_frame`	尾帧图片
`reference_image`	人物、服装、场景、物品等图片参考
`reference_video`	动作或镜头节奏参考
`reference_voice`	音频或声音参考

素材数量：最多 9 张图片、3 个视频、3 个音频。请确认链接可公开访问，不能使用本地电脑路径。使用 sd-2-c1 时，图片建议不小于 300 x 300 像素。

带图片参考的请求体

{
  "model": "seedance-2.0-0826",
  "input": {
    "prompt": "保持参考人物的外观和服装，人物转身看向镜头，镜头缓慢推进",
    "media": [
      {
        "type": "reference_image",
        "url": "https://cdn.example.com/reference.png"
      }
    ]
  },
  "parameters": {
    "duration": 5,
    "resolution": "720p",
    "ratio": "9:16"
  }
}

查询任务状态

创建任务后，seedance-2.0-0826 建议每隔 3-5 秒查询一次，sd-2-c1 建议每隔 20 秒以上查询一次。任务未完成时请继续轮询，不要提前调用下载接口。

PENDING

任务已创建，等待处理。

RUNNING

任务正在生成，继续轮询。

SUCCEEDED

视频已完成，可以下载。

FAILED

任务失败，请读取响应中的错误信息。也可能返回 FAILED: 错误原因。

cURL

curl --request GET "https://newapi.h5zoom.com/v1/videos/TASK_ID" \
  --header "Authorization: Bearer YOUR_API_KEY"

JavaScript 轮询示例

JavaScript

const baseUrl = "https://newapi.h5zoom.com/v1";
const apiKey = "YOUR_API_KEY";
const taskId = "TASK_ID";
const pollDelayMs = 20000; // sd-2-c1 使用 20000，seedance-2.0-0826 可使用 4000

async function getTask() {
  const response = await fetch(baseUrl + "/videos/" + taskId, {
    headers: { Authorization: "Bearer " + apiKey }
  });
  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

let task;
do {
  task = await getTask();
  if (typeof task.status === "string" && task.status.startsWith("FAILED")) {
    throw new Error(task.error?.message || "任务生成失败");
  }
  if (task.status !== "SUCCEEDED") {
    await new Promise(resolve => setTimeout(resolve, pollDelayMs));
  }
} while (task.status !== "SUCCEEDED");

console.log("任务完成:", task);

下载生成视频

仅当状态为 SUCCEEDED 时下载。下载接口仍需携带同一个 API Key。建议统一使用该接口保存成品，不要依赖任务响应中可能出现的临时结果地址。

cURL

curl --location "https://newapi.h5zoom.com/v1/videos/TASK_ID/content" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --output result.mp4

常见问题

现象	排查方式
401 或 token invalid	确认 Key 来自本站“令牌管理”，并使用 `Authorization: Bearer YOUR_API_KEY` 格式。
模型不可用	确认模型名为 `seedance-2.0-0826` 或 `sd-2-c1`，并确认你的令牌所在分组有调用权限。
参考素材失败	确认素材为公网 HTTPS URL，打开链接可直接访问，且素材类型与 `type` 对应。
任务状态为 FAILED	读取查询响应中的错误信息，修改提示词或素材后重新创建任务。
下载接口失败	先查询任务状态。只有 `SUCCEEDED` 才可以下载。
sd-2-c1 视频无法再访问	生成结果可能有保存时限。任务成功后请尽快通过下载接口保存到自己的存储位置。

调用前检查

Base URL 使用 https://newapi.h5zoom.com/v1
模型名使用 seedance-2.0-0826 或 sd-2-c1
请求头使用本站创建的 API Key
请求体采用 JSON 格式
保存创建响应中的任务 ID
参考素材使用可访问的公网 HTTPS URL
任务成功后再下载视频