特效 API

POST https://api.beatapi.io/v1/effects/tasks

使用已发布且有版本的 BeatAPI 特效创建异步图片或视频特效任务。

鉴权

Authorization   string   必填

在 Authorization 请求头中以 Bearer 令牌发送服务端 API 密钥，可在控制台创建。

Authorization: Bearer <BEATAPI_API_KEY>

永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 Content-Type: application/json。建议为每个逻辑创建请求设置唯一的 Idempotency-Key，只有完全相同的请求体才能安全复用原键。

请求体

字段名、类型和枚举值保留英文原样，用途和限制用中文说明。

本地素材无法通过公网 HTTPS URL 访问时，请先上传输入文件，再使用返回的 data.url。

effect_id   string   必填

已发布特效的稳定 ID。

effect_version   integer   选填

指定不可变的特效版本。省略时使用当前发布版本。

取值与默认值: 最小值 1

images   string[]   必填

按当前模型或工作流要求排序的公网 HTTPS 图片 URL 列表。

取值与默认值: 1–7 项

options   object   选填

所选特效版本支持的可选控制项。请以特效目录返回的规则为准。

options.aspect_ratio   string   选填

输出素材的宽高比。

options.resolution   string   选填

输出素材的分辨率或质量档位。

options.duration   integer   选填

请求的输出时长，单位为秒。

options.bgm   boolean   选填

当所选特效支持时，是否加入背景音乐。

options.seed   integer   选填

可复现生成结果的随机种子。按页面规则使用 -1 时会随机生成。

响应

成功请求返回 HTTP 201，响应体如下。

1
{
2
  "data": {
3
    "id": "task_effect123",
4
    "object": "task",
5
    "task_kind": "effect",
6
    "capability_id": "video-muscle-max",
7
    "capability_version": 1,
8
    "effect_id": "video-muscle-max",
9
    "effect_version": 1,
10
    "status": "queued",
11
    "stage": "queued",
12
    "created_at": 1782210000,
13
    "updated_at": 1782210000,
14
    "completed_at": null,
15
    "output": null,
16
    "usage": {
17
      "credits_reserved": 1.2,
18
      "credits_charged": 1.2,
19
      "credits_settled": 0,
20
      "credits_refunded": 0
21
    },
22
    "request_id": "req_effect123",
23
    "error_code": null,
24
    "error_message": null
25
  }
26
}

下一步

保存接受响应中的 data.id，每 5–10 秒轮询 GET /v1/tasks/{task_id}。任务成功后从 data.output.media 读取托管结果。

错误