FreeRap 模板 API

认证

创建和查询任务都必须携带 Authorization 请求头。使用「设置 → API」中的完整 sk_ 密钥。密钥缺失或无效时返回 HTTP 401。不要在浏览器代码中暴露密钥。

Authorization: Bearer <API_KEY>

接口约定

模板提供提示词、参考视频和配乐；调用方提供参考图片和生成参数。不支持回调地址，请查询任务获取结果。

请求成功时返回 HTTP 200、code 0、message ok 及 data 对象。请求失败时返回 code -1 和 message。查询成功时，data.status 仍可能表示生成失败。

创建任务

为启用的模板创建异步视频生成任务。HTTP 200 表示任务已创建，视频仍在生成中。

必需请求头：Authorization: Bearer <API_KEY> 和 Content-Type: application/json。

路径参数

请求体

新接入统一使用 reference_image_urls、model 和 resolution。下表为所有模板通用的请求字段。

成功响应

以下数值仅为示例。30 积分不是固定价格，请以请求实际返回的报价为准。

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "credits_estimate": 30,
    "credits_charged": 30
  }
}

curl --request POST \
  'https://freerapvideo.com/api/v1/templates/YOUR_TEMPLATE_SLUG/generations' \
  --header "Authorization: Bearer $FREERAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "reference_image_urls": ["https://cdn.example.com/image-1.jpg", "https://cdn.example.com/image-2.jpg", "https://cdn.example.com/image-3.jpg"],
    "model": "pro",
    "resolution": "720p"
  }'

查询任务

查询当前 API 密钥所属用户通过 API 创建的任务。无需请求体。可使用创建时的密钥，或同一用户的其他有效密钥。

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "campaign": "bulin",
    "costCredits": 30,
    "credits_estimate": 30,
    "credits_charged": 30,
    "createdAt": "2026-10-31T00:00:00.000Z",
    "videos": [
      "https://media.example.com/generated/video.mp4"
    ]
  }
}

任务状态

建议约每 30 秒查询一次，进入终态后停止。查询超时不代表生成失败，请继续查询原任务。

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "campaign": "bulin",
    "costCredits": 0,
    "credits_estimate": 30,
    "credits_charged": 0,
    "createdAt": "2026-10-31T00:00:00.000Z",
    "videos": [],
    "error": "Video generation failed."
  }
}

错误响应

请求错误使用非 2xx HTTP 状态码及以下响应体，code 均为 -1。通过 HTTP 状态码区分错误类别。message 是说明文本，不是稳定的机器可读错误标识。

{
  "code": -1,
  "message": "Insufficient credits."
}

积分与限流

创建任务时预留积分。pending 或 processing 期间，credits_charged 等于 credits_estimate。成功后保留扣费；失败或取消后退还预留积分，扣除已配置的失败费用（默认为 0）。终态响应中的 credits_charged 为最终扣费。

每个 API 密钥最多同时有 30 个 pending 或 processing 任务。在单个服务实例上，每个密钥最多每秒创建一次、每秒查询五次。HTTP 429 可能带有以秒为单位的 Retry-After；未提供时，请等待后重试。