把视频创作接入你的应用。
获取报价,提交任务,取回视频。网页与 API 共用账户和余额。
快速开始
先在工作台 → 账户创建 API 密钥,并在运行环境中设置 H3_API_KEY。以下示例会在你确认报价后创建真实任务。
# 需要 curl 和 jq;先在运行环境设置 H3_API_KEY
BASE_URL='https://你的域名'
: "${H3_API_KEY:?请先设置 H3_API_KEY}"
# 1. 读取当前可用参数(能力会随配置、售价与时段变化)
curl --fail-with-body -sS "$BASE_URL/v1/capabilities?model_id=h3-video" | jq
# 2. 获取报价;示例参数须在上面的 variants 中受支持
PARAMS='{"model_id":"h3-video","resolution":"480p","duration":5,"aspect_ratio":"landscape","mode":"text","image_count":0}'
QUOTE=$(curl --fail-with-body -sS "$BASE_URL/v1/quote" \
-H "Authorization: Bearer $H3_API_KEY" \
-H 'Content-Type: application/json' -d "$PARAMS") || exit 1
printf '%s\n' "$QUOTE" | jq '.quote | {amount, currency, breakdown, valid_until}'
# 3. 确认费用后提交(会冻结真实余额)
printf '输入 yes 确认本次费用:'
read -r CONFIRM
[ "$CONFIRM" = yes ] || exit 0
QUOTE_ID=$(printf '%s' "$QUOTE" | jq -er '.quote.quote_id') || exit 1
REQUEST_ID=$(uuidgen)
BODY=$(jq -n --argjson p "$PARAMS" --arg q "$QUOTE_ID" \
'$p | del(.image_count) | . + {quote_id:$q, prompt:"清晨的海边,镜头缓缓向前推进", image_ids:[]}')
# 提交前保存原请求;不含 API Key,响应丢失后可从文件恢复
PENDING_FILE="h3-pending-$REQUEST_ID.json"
jq -n --arg key "$REQUEST_ID" --argjson body "$BODY" \
'{idempotency_key:$key, body:$body}' > "$PENDING_FILE" || exit 1
# 恢复时从原文件读取 REQUEST_ID 与 BODY,保持原内容重试:
# REQUEST_ID=$(jq -er '.idempotency_key' "$PENDING_FILE")
# BODY=$(jq -c '.body' "$PENDING_FILE")
JOB=$(curl --fail-with-body -sS "$BASE_URL/v1/generations" \
-H "Authorization: Bearer $H3_API_KEY" \
-H "Idempotency-Key: $REQUEST_ID" \
-H 'Content-Type: application/json' -d "$BODY") || exit 1
JOB_ID=$(printf '%s' "$JOB" | jq -er '.id') || exit 1
printf '任务编号:%s\n' "$JOB_ID"
# 4. 每隔 3 秒查询;succeeded 后下载,failed 后已自动解冻
curl --fail-with-body -sS "$BASE_URL/v1/generations/$JOB_ID" \
-H "Authorization: Bearer $H3_API_KEY" | jq
# 仅在 status=succeeded 且 result.state=available 后执行:
# 将查询响应的 result_url 保存为 RESULT_URL,先鉴权取得签名地址再单独下载:
# COS_URL=$(curl --fail-with-body -sS "$BASE_URL$RESULT_URL/access" \
# -H "Authorization: Bearer $H3_API_KEY" | jq -r .url)
# curl --fail-with-body -o "$JOB_ID.mp4" "$COS_URL"鉴权与地址
本站 API 地址如下,路径以 /v1 开头。通过你的服务端发送请求,密钥不要放进网页源码或公开仓库。
https://你的域名Authorization: Bearer <H3_API_KEY>公开模型和能力接口无需鉴权。报价、任务、上传、下载和账单均要求 API Key。只能访问当前账户的资源;密钥创建与撤销在网页账户中完成。
"0.20"。接入端使用 Decimal 等精确十进制类型,展示和确认费用以服务端报价为准。模式与参数
先读取 GET /v1/capabilities?model_id=h3-video。每个 variant 是一组完整能力,不能将不同组合的清晰度、秒数和比例随意拼接。
只使用文字,不携带图片。
{
"model_id": "h3-video",
"resolution": "480p",
"duration": 5,
"aspect_ratio": "landscape",
"mode": "text",
"image_count": 0
}{
"model_id": "h3-video",
"resolution": "480p",
"duration": 5,
"aspect_ratio": "landscape",
"mode": "text",
"quote_id": "33333333-3333-4333-8333-333333333333",
"prompt": "清晨的海边,海浪轻轻拍打沙滩,镜头缓缓向前推进",
"image_ids": []
}| 字段 | 类型 | 说明 |
|---|---|---|
model_id | string | 模型编号,通过 /v1/models 获取;默认 h3-video。 |
mode | text | frames | reference | lipsync | 文生、首尾帧、多参考、音频对口型。默认 text。 |
resolution | string | 如 480p、736p、768p、1080p;以当前 variants 为准。 |
duration | integer | 视频秒数,必须在该组合的 duration_min–duration_max 内。 |
aspect_ratio | landscape | portrait | square | 横屏、竖屏、方形,必须属于该组合的 aspect_ratios。 |
image_count | integer | 只用于报价。文生 0、首尾帧 2、对口型 1、多参考为实际张数。 |
seed | string,可选 | 最多 15 位十进制整数字符串;仅 seed=true 的组合支持,下限取 seed_min(缺省 1)。报价和生成须相同。 |
quote_id | UUID,生成必填 | 当前参数的报价编号。更改参数必须重新报价。 |
prompt | string | 其他模式必填 1–6000 字符描述;对口型由音频驱动,省略或传空字符串。 |
audio_count / audio_ids | integer / UUID[] | 报价传音频数量,生成传音频 asset.id。对口型必须一段,其他方式受 max_audios 限制。 |
image_ids | UUID[] | 多参考模式为 1–max_images 张,最多 9 张;对口型必须一张图片 asset.id。其他模式为 []。 |
first_frame_id / last_frame_id | UUID,首尾帧必填 | 分别绑定开始与结束的图片 asset.id;其他模式不传。 |
报价默认参数为文生、480p、5 秒、横屏、0 张图;建议显式传入。报价最多有效 60 秒,临近峰谷或调价边界会缩短;更改任一参数后重新获取 quote_id。
上传素材
每次上传一张静态 JPEG、PNG 或 WebP,不超过 20 MiB。使用 multipart 字段 file;浏览器或 curl 会自动设置 Content-Type 和 boundary,无需手动填写。
图片统一为无损 WebP。音频原格式上传添加 X-Media-Type: audio,统一为 PCM16 / 48kHz WAV,最长 120 秒且保留 1–2 声道。
已规范化的文件可调用 POST /v1/uploads/direct,JSON 包含 media_type、bytes、sha256;按返回的 transfer URL/headers PUT 文件后,再调用 POST /v1/uploads/回执ID/complete。COS 请求不能携带本站 API Key。
音频能力以 max_audios 为准,当前两个 v2 工作流最多 3 段;报价带 audio_count,生成带相同数量的 audio_ids,没有音频时省略。
BASE_URL='https://你的域名'
IMAGE='./image.png'
UPLOAD_KEY=$(uuidgen)
# macOS 自带 shasum;Linux 也可用 sha256sum
SHA256=$(shasum -a 256 "$IMAGE" | cut -d ' ' -f 1)
UPLOAD=$(curl --fail-with-body -sS "$BASE_URL/v1/files" \
-H "Authorization: Bearer $H3_API_KEY" \
-H "Idempotency-Key: $UPLOAD_KEY" \
-H "X-Upload-SHA256: $SHA256" \
-F "file=@$IMAGE") || exit 1
UPLOAD_ID=$(printf '%s' "$UPLOAD" | jq -er '.id') || exit 1
# 使用上传响应中的 id;它与成功后的 asset.id 含义不同
curl --fail-with-body -sS "$BASE_URL/v1/uploads/$UPLOAD_ID" \
-H "Authorization: Bearer $H3_API_KEY"
# 只有 status=succeeded 后,才把 asset.id 用作生成参数中的图片编号。
# 响应丢失时保持原 UPLOAD_KEY、SHA256 和文件重试。接收成功为 202,查询状态可为 receiving、queued、processing、succeeded、failed。只有 succeeded 响应里的 asset.id 才能用于生成;失败时读取 error.code/message。
上传必须提供 UUID Idempotency-Key 和原文件 64 位小写十六进制 X-Upload-SHA256。响应丢失时重用原编号、摘要和文件;已完成请求的重试返回 200。相同编号改变内容会返回 409,排队与处理总期限为接收完成后 15 分钟。
任务与费用
首次提交返回 202 和任务对象;原请求重试返回 200 和同一任务。系统自动调度等待中的任务,关闭网页不影响执行。
| status | 含义 | 资金状态 |
|---|---|---|
queued | 已接收,等待自动执行 | 金额已冻结,尚未扣费 |
processing | 正在处理 | 继续冻结 |
needs_attention | 原任务结果仍在核对,继续查询 | 继续冻结,不创建新任务 |
succeeded | 成功,可读取 result_url | 已扣费 |
failed | 失败,查看 message | 全部解冻,本次扣费为零 |
每隔 3–10 秒查询 /v1/generations/任务编号。任务包含公开生成参数、amount、currency、billing、created_at、updated_at、result、result_url 和 message。billing 返回 state、frozen、charged、unfrozen、refunded、net_charged,金额均为字符串。
按秒收费时,总价 = 单价 × 秒数;报价的 breakdown 提供 unit_price、quantity 和 basis(per_second / per_job)。提交时锁定金额,等待跨越峰谷或后续调价都不会改变已接收任务的费用。
作品历史使用 GET /v1/generations。首屏包含全部未完成任务和最近 24 条终态任务;将返回的 next_cursor 作为 before 查询参数读取下一页,为 null 时已读完。按创建时间和任务编号倒序排列,刷新首屏时按 id 合并,保留已加载的历史。单个任务的实时状态使用详情接口查询。
图片与视频默认保留 24 小时,具体以 expires_at 为准。图片从处理完成、视频从生成成功计时。任务成功不代表资源永久可用:result.state=expired 时 result_url 为 null;过期下载返回 410。账单与任务记录继续保留。
先用本站鉴权获取 /v1/files/文件ID/access,再用返回的签名 URL 单独下载,不向 COS 转发 API Key。COS 支持 Range: bytes=0-1023。签名到期可重新获取,资源到期不能延长。请检查 HTTP 状态,不把错误 JSON 保存为视频。
接口一览
| 方法 | 路径 | 鉴权 | 响应说明 |
|---|---|---|---|
| GET | /v1/models | 公开 | 可用模型:{ models: [{ id, name }] } |
| GET | /v1/pricing?model_id=… | 公开 | 当前可售价格示例:{ model, observed_at, valid_until, examples };只读价目,不生成报价凭证 |
| GET | /v1/capabilities?model_id=… | 公开 | 当前可售参数组合 variants、max_image_bytes、seed_max |
| POST | /v1/quote | API Key | 获取并锁定报价:{ quote: { quote_id, amount, currency, breakdown, period, timezone, valid_until } } |
| GET | /v1/quote?… | API Key | 相同报价参数放在查询字符串,响应与 POST 相同 |
| POST | /v1/generations | API Key | 创建任务,首次 202、同一请求重放 200 |
| GET | /v1/generations/{id} | API Key | 查询本人任务及结果 |
| GET | /v1/generations | API Key | { jobs: [...], next_cursor },全部未完成任务与最近 24 条终态;before=next_cursor 获取更早的终态任务 |
| POST | /v1/files | API Key | 原格式素材 multipart 上传并规范化,接收返回 202 Upload |
| POST | /v1/uploads/direct | API Key | 规范文件 JSON 申请 COS 直传地址 |
| POST | /v1/uploads/{id}/complete | API Key | 完成直传并排队核验 |
| GET | /v1/files/{id}/access | API Key | 获取私有签名 URL 和 URL/资源期限 |
| GET | /v1/uploads/{id} | API Key | Upload:{ id, status, asset, error } |
| GET / HEAD | /v1/files/{id} | API Key | 鉴权后 307 到 COS;Range 由 COS 处理,资源过期返回 410 |
| GET | /v1/account | API Key | 账户、balance.available/frozen 与 spending 累计费用 |
| GET | /v1/ledger | API Key | { entries: [...] },最近 100 条人民币账务明细 |
所有列表当前不提供游标分页。账户和账本接口返回累计消费、收付款及冻结变动;查询、下载不会产生新的生成费用。
错误与重试
{
"error": {
"code": "invalid_quote",
"message": "报价与当前参数不匹配,请重新获取报价",
"request_id": "服务端请求编号"
}
}生成的 Idempotency-Key 长度 8–128,仅使用字母、数字、下划线、点、冒号、连字符。超时或断网不等于任务失败。保存原 JSON 和编号并原样重试;有任务编号后只查询该任务,不能重新调用创建接口来“重试生成”。
| HTTP | code | 处理方式 |
|---|---|---|
| 400 | invalid_parameters | 检查字段、类型、模式和图片数量。 |
| 401 | unauthorized | 检查 API Key 是否正确、已撤销或账户已停用。 |
| 403 | password_change_required | 先在网页修改临时密码。 |
| 404 | not_found | 确认任务或文件属于该 Key 对应的账户。 |
| 409 | invalid_quote / price_changed | 尚未接收任务:重新报价、确认费用后再提交。 |
| 409 | idempotency_conflict | 同一编号的内容不一致;恢复原始请求,不要更换内容重试。 |
| 409 | insufficient_balance | 可用余额不足,冻结金额不能用于新任务。 |
| 409 | storage_limit | 图片存储配额不足,等待资源到期清理。 |
| 410 | asset_expired | 图片重新上传;已到期的视频无法再次下载。 |
| 413 | file_too_large / input_too_large | 压缩图片;单张上限 20 MiB,并受生成方式总大小限制。 |
| 429 | upload_busy / rate_limited / job_queue_full | 遵守 Retry-After,保留原请求编号与内容重试。 |
| 503 | price_unavailable / service_unavailable / storage_full | 稍后再试或联系服务方。提交响应不确定时只核对原任务。 |
参数错误可能带有 fields。遇到无法确认的问题,保留任务编号、错误 code 和 request_id 供服务方排查。