把视频创作接入你的应用。

获取报价,提交任务,取回视频。网页与 API 共用账户和余额。

创建密钥确认报价提交生成下载视频

快速开始

先在工作台 → 账户创建 API 密钥,并在运行环境中设置 H3_API_KEY。以下示例会在你确认报价后创建真实任务。

从报价到生成 · cURL + jq
# 需要 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 开头。通过你的服务端发送请求,密钥不要放进网页源码或公开仓库。

Base URL
https://你的域名
鉴权请求头
Authorization: Bearer <H3_API_KEY>

公开模型和能力接口无需鉴权。报价、任务、上传、下载和账单均要求 API Key。只能访问当前账户的资源;密钥创建与撤销在网页账户中完成。

金额单位是人民币元,使用十进制字符串,例如 "0.20"。接入端使用 Decimal 等精确十进制类型,展示和确认费用以服务端报价为准。

模式与参数

先读取 GET /v1/capabilities?model_id=h3-video。每个 variant 是一组完整能力,不能将不同组合的清晰度、秒数和比例随意拼接。

只使用文字,不携带图片。

POST /v1/quote · 报价参数
{
  "model_id": "h3-video",
  "resolution": "480p",
  "duration": 5,
  "aspect_ratio": "landscape",
  "mode": "text",
  "image_count": 0
}
POST /v1/generations · 替换报价与图片 UUID
{
  "model_id": "h3-video",
  "resolution": "480p",
  "duration": 5,
  "aspect_ratio": "landscape",
  "mode": "text",
  "quote_id": "33333333-3333-4333-8333-333333333333",
  "prompt": "清晨的海边,海浪轻轻拍打沙滩,镜头缓缓向前推进",
  "image_ids": []
}
字段类型说明
model_idstring模型编号,通过 /v1/models 获取;默认 h3-video。
modetext | frames | reference | lipsync文生、首尾帧、多参考、音频对口型。默认 text。
resolutionstring如 480p、736p、768p、1080p;以当前 variants 为准。
durationinteger视频秒数,必须在该组合的 duration_min–duration_max 内。
aspect_ratiolandscape | portrait | square横屏、竖屏、方形,必须属于该组合的 aspect_ratios。
image_countinteger只用于报价。文生 0、首尾帧 2、对口型 1、多参考为实际张数。
seedstring,可选最多 15 位十进制整数字符串;仅 seed=true 的组合支持,下限取 seed_min(缺省 1)。报价和生成须相同。
quote_idUUID,生成必填当前参数的报价编号。更改参数必须重新报价。
promptstring其他模式必填 1–6000 字符描述;对口型由音频驱动,省略或传空字符串。
audio_count / audio_idsinteger / UUID[]报价传音频数量,生成传音频 asset.id。对口型必须一段,其他方式受 max_audios 限制。
image_idsUUID[]多参考模式为 1–max_images 张,最多 9 张;对口型必须一张图片 asset.id。其他模式为 []。
first_frame_id / last_frame_idUUID,首尾帧必填分别绑定开始与结束的图片 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_typebytessha256;按返回的 transfer URL/headers PUT 文件后,再调用 POST /v1/uploads/回执ID/complete。COS 请求不能携带本站 API Key。

音频能力以 max_audios 为准,当前两个 v2 工作流最多 3 段;报价带 audio_count,生成带相同数量的 audio_ids,没有音频时省略。

上传与查询 · cURL + jq
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/quoteAPI Key获取并锁定报价:{ quote: { quote_id, amount, currency, breakdown, period, timezone, valid_until } }
GET/v1/quote?…API Key相同报价参数放在查询字符串,响应与 POST 相同
POST/v1/generationsAPI Key创建任务,首次 202、同一请求重放 200
GET/v1/generations/{id}API Key查询本人任务及结果
GET/v1/generationsAPI Key{ jobs: [...], next_cursor },全部未完成任务与最近 24 条终态;before=next_cursor 获取更早的终态任务
POST/v1/filesAPI Key原格式素材 multipart 上传并规范化,接收返回 202 Upload
POST/v1/uploads/directAPI Key规范文件 JSON 申请 COS 直传地址
POST/v1/uploads/{id}/completeAPI Key完成直传并排队核验
GET/v1/files/{id}/accessAPI Key获取私有签名 URL 和 URL/资源期限
GET/v1/uploads/{id}API KeyUpload:{ id, status, asset, error }
GET / HEAD/v1/files/{id}API Key鉴权后 307 到 COS;Range 由 COS 处理,资源过期返回 410
GET/v1/accountAPI Key账户、balance.available/frozen 与 spending 累计费用
GET/v1/ledgerAPI Key{ entries: [...] },最近 100 条人民币账务明细

所有列表当前不提供游标分页。账户和账本接口返回累计消费、收付款及冻结变动;查询、下载不会产生新的生成费用。

错误与重试

统一错误格式
{
  "error": {
    "code": "invalid_quote",
    "message": "报价与当前参数不匹配,请重新获取报价",
    "request_id": "服务端请求编号"
  }
}
一次生成,始终使用同一个幂等键。

生成的 Idempotency-Key 长度 8–128,仅使用字母、数字、下划线、点、冒号、连字符。超时或断网不等于任务失败。保存原 JSON 和编号并原样重试;有任务编号后只查询该任务,不能重新调用创建接口来“重试生成”。

HTTPcode处理方式
400invalid_parameters检查字段、类型、模式和图片数量。
401unauthorized检查 API Key 是否正确、已撤销或账户已停用。
403password_change_required先在网页修改临时密码。
404not_found确认任务或文件属于该 Key 对应的账户。
409invalid_quote / price_changed尚未接收任务:重新报价、确认费用后再提交。
409idempotency_conflict同一编号的内容不一致;恢复原始请求,不要更换内容重试。
409insufficient_balance可用余额不足,冻结金额不能用于新任务。
409storage_limit图片存储配额不足,等待资源到期清理。
410asset_expired图片重新上传;已到期的视频无法再次下载。
413file_too_large / input_too_large压缩图片;单张上限 20 MiB,并受生成方式总大小限制。
429upload_busy / rate_limited / job_queue_full遵守 Retry-After,保留原请求编号与内容重试。
503price_unavailable / service_unavailable / storage_full稍后再试或联系服务方。提交响应不确定时只核对原任务。

参数错误可能带有 fields。遇到无法确认的问题,保留任务编号、错误 code 和 request_id 供服务方排查。

准备好开始了?前往工作台