BeatAPI 快速指南

快速指南

文本、工作流、实时、视频、图片和特效 API 共用一套服务端 API 密钥。先完成下面三个步骤，再查看同步文本响应、任务字段、文件上传、额度限制和生产错误处理。

三步完成第一个任务

1. 创建 API 密钥

在 控制台 → API 密钥 创建密钥，然后在终端中安全载入，避免写入命令历史：

$read -rsp "BeatAPI API 密钥: " BEATAPI_API_KEY && echo
$export BEATAPI_API_KEY

所有请求使用 https://api.beatapi.io，并携带：

1Authorization: Bearer <BEATAPI_API_KEY>

2. 创建任务

下面用 POST /v1/images/tasks 提交最小图片请求：

$curl https://api.beatapi.io/v1/images/tasks \
>  -X POST \
>  -H "Authorization: Bearer $BEATAPI_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "model": "nano-banana",
>    "prompt": "暖色石材展台上的编辑风格产品摄影。"
>  }'

合法请求返回 201 Created。保存响应中的 data.id。

3. 轮询结果

$curl https://api.beatapi.io/v1/tasks/task_8K2qA \
>  -H "Authorization: Bearer $BEATAPI_API_KEY"

将 task_8K2qA 替换为上一步的 data.id。建议每 5–10 秒轮询一次并加入随机抖动。状态为 succeeded 时读取 data.output.media 并停止轮询；状态为 failed 时读取 data.error_code 和 data.error_message 后停止。

永久 API 密钥只能放在可信服务端，不能写进浏览器、移动端、公开脚本、日志或截图。实时 API 的浏览器端只接收由你的服务端创建的短期 client_secret。

选择 API

API创建操作输入结果
文本（GPT-5.6）POST /v1/responses文本、图片、工具和推理控制同步 JSON 或流式文本响应
音乐视频工作流POST /v1/music-video/tasks音频和对应套餐要求的视觉参考完整音乐视频和分镜信息
电商视频工作流POST /v1/ecommerce-video/tasks商品图片、时长和创意说明完整商品视频
视频分析工作流POST /v1/video-analysis/tasks已上传视频、分析提示词和分析深度分析文本和 Token 用量
实时 APIPOST /v1/realtime/sessions浏览器来源、固定时长和实时 MediaStream实时生成的 WebRTC 视频
视频 APIPOST /v1/videos/tasks模型专属提示词和媒体参考一个托管视频
图片 APIPOST /v1/images/tasks模型专属提示词和可选参考图一个托管图片
特效 APIPOST /v1/effects/tasks已发布特效 ID、图片和支持的参数一个托管图片或视频特效结果

文本调用会同步返回，或返回 SSE 事件流；实时 API 创建短期 Session。工作流、视频、图片和特效创建操作会返回异步任务，保存 data.id 后轮询统一任务接口。每个 API 密钥对任务查询接口的限制为每分钟 120 次。

GPT-5.6 模型选择、SDK 兼容格式和流式示例请查看 GPT-5.6 指南。

查询任务状态

GET /v1/tasks/{task_id}

参数位置类型必填规则
task_id路径string是使用创建响应中的 data.id

状态值

状态含义客户端动作
queued已接受，等待处理继续轮询
processing正在生成继续轮询
storyboard_ready音乐视频分镜已就绪自动流程可继续；需要时检查
requires_action音乐视频等待人工审核编辑或合成镜头
editing正在编辑音乐视频镜头继续轮询
composing正在合成音乐视频继续轮询
succeeded托管结果已就绪读取 data.output 并停止轮询
failed任务失败结束读取错误和退款字段并停止轮询

标准任务字段

字段类型出现条件含义
idstring始终稳定任务 ID
objectstring始终固定为 task
task_kindstring始终workflow、effect、image 或 video
capability_idstring始终稳定的工作流、特效或模型 ID
capability_versioninteger 或 null始终版本化能力的不可变版本
workflowstring工作流任务music-video、ecommerce-video 或 video-analysis
effect_idstring特效任务稳定特效 ID
effect_versioninteger特效任务已选择的不可变版本
media_typestring图片/视频任务image 或 video
modelstring图片/视频任务稳定公开模型别名
statusstring始终当前生命周期状态
stagestring始终当前处理阶段
storyboardobject音乐视频可用时返回分镜信息
created_at / updated_atinteger始终Unix 时间戳
completed_atinteger 或 null始终终态 Unix 时间戳
outputobject 或 null始终成功前为 null
usageobject始终USD 计费和可计费时长
request_idstring始终客服与排障关联 ID
error_code / error_messagestring 或 null始终机器可读和人类可读错误

为保持 API 兼容，公开字段仍使用 credits_reserved 等名称。所有 Credit 与余额数值都是美元账本金额，1 Credit 等于 1 美元，控制台使用 $ 展示同一数值。

字段类型含义
usage.credits_reservednumber为操作预留的 USD 金额
usage.credits_chargednumber接受任务时扣取的 USD 金额
usage.billable_duration_secondsinteger，可选用于计费的时长
usage.credits_settlednumber成功后最终结算的 USD 金额
usage.credits_refundednumber符合条件的失败所退回金额
output.mediaobject[]托管结果文件
output.media[].typestringimage 或 video
output.media[].urlstring托管结果 URL
output.media[].mime_typestring结果 MIME 类型
output.r2_urlstring主要托管结果 URL

上传输入文件

POST /v1/files

本地文件无法通过公共 HTTPS URL 访问时，先上传再使用返回的 data.url。每次上传必须带准确的 Content-Length；普通 cURL、浏览器和 SDK 会自动设置。未声明长度的分块上传会在读取正文前被拒绝。

字段类型必填默认值规则
filebinary是—单个支持文件；视频最大 100 MB，其他类型最大 50 MB
purposestring否input目前只支持 input
$curl https://api.beatapi.io/v1/files \
>  -X POST \
>  -H "Authorization: Bearer $BEATAPI_API_KEY" \
>  -F "file=@./song.mp3" \
>  -F "purpose=input"
素材扩展名MIME 类型附加规则
图片PNG、JPG/JPEG、WebPimage/png、image/jpeg、image/webp最大 50 MB
音频MP3、WAV、AAC、M4Aaudio/mpeg、audio/wav、audio/aac、audio/mp4最大 50 MB；10–300 秒
字幕SRTapplication/x-subrip；仅 .srt 文件可使用 text/plain最大 50 MB
动作参考视频MP4、MOVvideo/mp4、video/quicktime最大 100 MB；3–30 秒；用于 Kling Motion Control

不支持 PDF、普通文本、octet-stream、不支持的视频封装和 ZIP。BeatAPI 会校验 MIME 与文件签名，并在服务端读取视频时长和尺寸。工作流输入 URL 不能指向 localhost、私有网络或 data URL。

查询用量与限制

GET /v1/usage 是无参数鉴权接口：

$curl https://api.beatapi.io/v1/usage \
>  -H "Authorization: Bearer $BEATAPI_API_KEY"

重点字段包括当前美元余额 credit_balance、任务总数 total_tasks、结算与退款金额、并发上限及占用，以及按工作流、能力、模型和 API 密钥的统计。余额可能为负；余额不足时不能创建新的付费任务。

错误与重试策略

1{
2  "error": {
3    "code": "rate_limit_exceeded",
4    "message": "Too many requests.",
5    "request_id": "req_abc123",
6    "retry_after_seconds": 12
7  }
8}

BeatAPI 只公开稳定错误码；内部供应商错误会被标准化，不属于客户契约。

错误码含义客户端动作
bad_request字段、组合、格式、URL 或限制不合法修正请求后再试
unauthorized / forbidden密钥无效或账号无权限检查有效的 Bearer 密钥和权限
not_found资源不存在或不属于当前密钥检查 ID 和归属
insufficient_credits余额不足充值后再创建付费操作
idempotency_conflict同一幂等键对应不同请求体相同逻辑请求复用原键，否则换新键
user_concurrency_exceeded活跃任务已达并发上限等待任务结束或提升额度
rate_limit_exceeded超过请求频率遵守 Retry-After 或 retry_after_seconds
content_policy_violation提示词或媒体违反内容政策修改内容后重新提交
processing_unavailable处理容量暂不可用按返回延迟等待；已接受任务继续轮询
processing_failed / processing_timeout任务失败或超时停止轮询，检查错误与退款，再判断是否新建任务
result_transfer_failed结果未能保存到一方存储检查退款后按需重试
invalid_signatureWebhook 签名或时间戳无效用原始字节、时间戳和 Secret 重新验证
实时 API 专属错误未启用、无容量、会话过期、来源或密钥无效按错误创建新会话或修正来源和权限
internal_errorBeatAPI 内部异常保留 request_id，仅在安全时重试或联系支持

实时会话创建必须使用 1–128 字符的 Idempotency-Key。工作流、图片、视频和特效任务创建可选幂等键，只可对完全相同的逻辑请求复用。

生产检查清单

  • 使用准确的 https://api.beatapi.io 域名。
  • 永久 API 密钥只放在可信服务端。
  • 按对应 API 页面校验字段、枚举、限制和条件组合。
  • 启动后台处理前保存任务或会话 ID 与 request_id。
  • 轮询加入随机抖动，并在终态或人工动作状态停止。
  • 遵守 HTTP 状态码、Retry-After 和 retry_after_seconds。
  • JSON 解析前，对 Webhook 原始字节验证签名。
  • 记录预留、结算、退款、错误和最终输出 URL。
  • 处理摄像头、人脸、声音或参考素材前，查看隐私政策和服务条款。