> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 特效 API

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

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

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

## 鉴权

`Authorization`   `string`   **必填**

在 `Authorization` 请求头中以 Bearer 令牌发送服务端 API 密钥，可在[控制台](https://beatapi.io/dashboard)创建。

```
Authorization: Bearer <BEATAPI_API_KEY>
```

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

## 请求体

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

本地素材无法通过公网 HTTPS URL 访问时，请先[上传输入文件](/quick-guide#upload-an-input-file)，再使用返回的 `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`，响应体如下。

```json
{
  "data": {
    "id": "task_effect123",
    "object": "task",
    "task_kind": "effect",
    "capability_id": "video-muscle-max",
    "capability_version": 1,
    "effect_id": "video-muscle-max",
    "effect_version": 1,
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 1.2,
      "credits_charged": 1.2,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_effect123",
    "error_code": null,
    "error_message": null
  }
}
```

## 下一步

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

## 错误

| 状态码   | 含义与处理方式                                                                                                                                                                                                                                                                  |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | JSON 格式错误，或字段、取值、参数组合不被接受（`bad_request`，错误信息会点名字段）；输入未通过内容审核时为 `content_policy_violation`。修正后再请求，原样重试仍会失败。                                                                                                                                                               |
| `401` | 未提供 API 密钥（`missing_api_key`），或密钥错误、已过期、已停用或额度已用尽（`invalid_api_key`，错误信息会说明是哪一种）。不要原样重试。                                                                                                                                                                                 |
| `402` | 余额不足（`insufficient_credits`）：账户余额为零或低于本次请求的价格。充值后再请求。                                                                                                                                                                                                                    |
| `403` | 密钥或账户无权执行该调用（`forbidden`），例如免费额度不能使用该模型（充值即可解锁）、请求来源不在密钥的 IP 白名单内，或模型不在密钥的分组里。不要原样重试。                                                                                                                                                                                    |
| `404` | 请求的模型、能力、任务、特效或版本不存在或当前不可用（`not_found`）。                                                                                                                                                                                                                                 |
| `409` | 幂等键在 24 小时内已用于其他请求体或路径，或使用该键的首个请求仍在处理中（`idempotency_conflict`）。只对完全相同的请求复用原键。                                                                                                                                                                                            |
| `429` | 请求过于频繁（`rate_limit_exceeded`，含免费模型限额）。按 `Retry-After`（也在 `error.retry_after_seconds`）等待后重试。                                                                                                                                                                              |
| `500` | 内部异常（`internal_error`），可以重试；持续出现时请保留 `request_id` 联系支持。                                                                                                                                                                                                                  |
| `503` | 请求未能完成（`processing_unavailable`、`processing_timeout`、`processing_failed` 或 `result_transfer_failed`），未扣费，可退避重试；503 不带 `Retry-After` 和 `retry_after_seconds`。BeatAPI 不返回 502 或 504。实时接口在本部署未启用时为 `realtime_disabled`（不可重试），容量暂时不足时为 `realtime_capacity_unavailable`（可重试）。 |