视频生成 API 快速入门：创建、查询与下载

使用本站 API，可以选择可用模型、预估积分、创建一次异步视频任务、查询状态并下载结果。这是本站独立平台的 API，不是 Pika 官方 API；本站当前尚未提供 Pika H3 Flex 模型本身。 请使用本站目录返回的模型 ID。

接口约定于 2026 年 11 月 9 日按本站实现核对。可下载示例通过模拟响应和本地未登录请求验证，不声称已经执行过付费供应商的端到端生成。

1. 创建 API Key

登录后打开设置 → API 密钥，为集成创建密钥，通过后端环境变量 API_KEY 提供，不要写进前端包、公开仓库或 URL。

生成与任务查询接受 Authorization: Bearer sk_...。显式凭证无效时，即使浏览器另有有效登录状态也会被拒绝。密钥使用所属账号及其积分余额。

基础地址使用 https://pikah3flex.com。中英文 API 都使用 /api/...，不要加 /zh 前缀。

方法与路径	用途	鉴权
GET /api/ai/router01/models?projectOnly=1&type=video	查看项目视频模型和当前 params	公开目录，无需密钥
POST /api/ai/router01/quote	验证输入并预估积分	公开估算，不创建任务
POST /api/ai/generate	创建任务并扣减积分	你的 API Key
GET /api/ai/task?taskId=...	查询同一账号所属任务	同一账号的 API Key

上传接口、/api/download、/api/storage/download 及账户管理接口并非都支持 API Key。目前上传和下载代理需要浏览器登录状态。服务端集成请提供可访问的素材 URL，并直接从结果 URL 下载。不要假设 /api/credits 接受此 API Key；余额和记录可在账户界面查看。

2. 先查模型，再选设置

export API_BASE_URL='https://pikah3flex.com'
curl -sS "${API_BASE_URL}/api/ai/router01/models?projectOnly=1&type=video"

成功响应的 code 为 0，data 是模型数组，包含 slug、type、name、params 等信息。先确认允许值、最小值、最大值、必需输入和默认值。项目目录为空，不代表任意平台模型都能生成；目标模型缺失时请联系支持。

下例假设当前目录中的 seedance-2.0-mini 支持 4 秒、480p、16:9。请先核实，或改选其他模型及其支持的参数。

3. 用准备提交的同一份参数询价

将以下内容保存为 request.json：

{
  "mediaType": "video",
  "model": "seedance-2.0-mini",
  "prompt": "A ceramic cup on a wooden table. One slow camera push-in, soft morning light, restrained movement.",
  "options": {
    "mode": "text-to-video",
    "visibility": "private",
    "duration": 4,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }
}

curl -sS "${API_BASE_URL}/api/ai/router01/quote" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

data.credits 是完整一次任务的积分预估。priceUsd、scope、provider 等描述报价计算；供应商美元金额不是单独的现金结算价，也不一定等于购买积分后的实际分摊成本。换算说明见积分成本与积分包折算。

询价不锁定价格或任务名额，提交时会重新计价。请求中的自填价格或余额不能作为计费依据。

4. 只提交一次，并保存本地任务 ID

这个 POST 可能消耗积分。 确认报价和设置后再执行：

curl -sS "${API_BASE_URL}/api/ai/generate" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

成功响应的 data 包含 id、dbId、taskId、taskStatus、taskInfo、costCredits、remainingBalance，初始状态为 queued。轮询前保存 dbId 或 id，作为稳定的查询 ID；后续响应也可能包含供应商任务 ID。

必须同时检查 HTTP 状态和 JSON 响应体。部分参数及业务错误会返回 HTTP 200，但 code: -1 并带有 message，不能仅凭 HTTP 200 判断任务创建成功。当前接口没有已公开约定的客户端幂等键；生成 POST 超时或响应丢失时，请先检查“我的创作”，必要时联系支持，不要直接重复提交。

5. 查询状态，再下载

curl -sS --get "${API_BASE_URL}/api/ai/task" \
  -H "Authorization: Bearer ${API_KEY}" \
  --data-urlencode "taskId=${VIDEO_TASK_ID}"

单 ID 查询的 data 是一个任务对象。

data.taskStatus	下一步
queued、pending、processing	保留 ID，间隔合理时间再次查询，例如 10 秒
success	从 data.taskInfo.videos[].videoUrl 取得所需输出并下载
failed、canceled	查看 data.taskInfo.userErrorCode，再核对任务和积分记录

停止轮询不会取消任务，客户端等待期限结束也不证明服务端失败。批量查询使用 taskIds，返回 data.tasks，当前最多 10 个 ID，不要与单任务返回结构混淆。

从后端或 curl 直接下载返回的 HTTPS 媒体 URL，不要把本站 API Key 转发给媒体域名。下载链接失败时先查询已有任务，按情况重试下载，不要仅为下载而重新生成。带签名的结果链接也不宜公开分享。

可运行的 Node.js 示例

下载 video-api-quickstart.mjs，使用 Node.js 22 或更高版本运行，仅依赖内置模块。先在后端环境中设置 API_KEY。

# 默认只查目录和询价。
node video-api-quickstart.mjs

# 确认报价后，允许创建一次新任务。
SUBMIT_VIDEO=1 node video-api-quickstart.mjs

# 继续查询已有任务，不创建新任务。
VIDEO_TASK_ID='your_saved_local_task_id' node video-api-quickstart.mjs

可选设置包括 API_BASE_URL、VIDEO_MODEL、VIDEO_DURATION、VIDEO_RESOLUTION、VIDEO_RATIO。示例会按目录验证基础参数，最多提交一次，最多查询 60 次，每次之间等待 10 秒，并将结果写入新的 video-<任务ID>.<格式>，不覆盖已有文件，也不会向媒体域名转发密钥。这个短视频示例会在内存中缓冲下载；处理更大的生产素材时请使用流式写入。

轮询结束或读取失败后，保留任务 ID 并继续查询。示例遇错停止，不自动重试付费 POST。如果未设置 VIDEO_TASK_ID 却再次以 SUBMIT_VIDEO=1 运行，可能创建另一个计费任务。

增加图片与参考输入

示例显式设置 options.visibility: "private"，以排除公开作品展示；省略时任务可能被视为可公开。这不保证媒体链接需要登录、零留存或供应商不训练，提交保密素材前请阅读隐私与商用说明。

使用顶层 imageUrls、videoUrls、audioUrls，保持相同的 options 结构。图生视频选择 options.mode: "image-to-video"，在 imageUrls 中提供首帧；参考生视频使用 options.mode: "reference-to-video"，只添加该模型支持的类型和数量。不要套用上游接口的 input 包装，也不要假设所有模型支持纯音频参考。

素材在处理期间必须能被供应商访问，本地文件路径或依赖浏览器 Cookie 的 URL 不适用。上传支持、模型输入限制和供应商计费是不同的检查项。更换输入后重新询价，尤其是视频、音频时长改变时。

失败与公开任务错误码见视频排错指南，创作修改见提示词指南。联系支持时提供任务 ID、模型、时间和已脱敏请求，不要发送 API Key。