API 实操

Hypit API 中文教程：查询模型、生成视频与下载结果

从模型目录到异步视频任务，说明认证、参考输入、幂等提交、状态轮询、结果下载和常见错误。

HypitAI 编辑整理 · 核对日期 2026-09-18

先确认这是托管 API 路线

直接调用 API 与在本地项目中运行 Agent、Run 和 Build 是两条入口。API 提交单项生成任务；完整复刻仍需要脚本、编排和验收。

读取当前账户可用模型

能否用于视频以模型卡的 endpoints 为准，不把公开页面上的模型名假设为所有账户都可用。密钥只从服务器环境变量读取。

curl https://hypit.ai/v1/models \
  -H "Authorization: Bearer $HYPIT_API_KEY"

提交最小视频任务

HTTP 202 和 job id 表示任务已接收或排队，不代表已经生成。规格必须落在当前模型卡支持范围内。

curl https://hypit.ai/v1/videos \
  -H "Authorization: Bearer $HYPIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ranking-demo-v1" \
  -d "{\"model\":\"bytedance/seedance-2\",\"prompt\":\"a presenter introduces a ranked list\",\"seconds\":5,\"resolution\":\"720p\",\"aspect_ratio\":\"9:16\"}"

选择正确的参考输入槽位

参考图片、首帧、尾帧、参考视频和 video-to-video 来源含义不同。

选择正确的参考输入槽位
目标	字段示例	注意
参考外观	input_reference / reference_image_urls	不同于首帧
固定开头或结尾	first_frame / last_frame	模型必须支持
参考动作或节奏	reference_videos	URL 可访问且满足时长限制
视频转视频	ref_video_url	取决于模型能力
参考声音	reference_audios	格式和模型都要支持

轮询状态，再取得素材

使用原 job id 查询到 succeeded、failed 或 queue_expired 等终态。成功后从 assets 取得签名链接；链接有效期有限，需要时重新获取。

curl https://hypit.ai/v1/jobs/<job-id> -H "Authorization: Bearer $HYPIT_API_KEY"
curl https://hypit.ai/v1/jobs/<job-id>/assets -H "Authorization: Bearer $HYPIT_API_KEY"

重试保留同一个幂等键

网络中断时服务端可能已接收任务。先查原任务；同一业务请求保留 Idempotency-Key，模型或输入变化则使用新的业务键并记录差异。

按错误位置排查

400 表示字段或输入无效；404 model_not_found 表示该 Key 无法在此端点路由模型；429 遵循 Retry-After；queue_expired 是终态。记录脱敏请求 ID、时间、模型和状态，不记录密钥。