> 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`   **필수** BeatAPI API 키를 Bearer 토큰으로 보내세요. 키는 [대시보드](https://beatapi.io/dashboard)에서 만들 수 있습니다. ``` Authorization: Bearer ``` 영구 API 키는 신뢰할 수 있는 서버에만 보관하세요. 요청 본문에는 `Content-Type: application/json`이 필요합니다. `Idempotency-Key`는 엔드포인트가 지원하는 경우 선택 사항이며, 완전히 같은 본문으로 안전하게 재시도하려면 사용하는 것이 좋습니다. ## 요청 본문 `effect_id`   `string`   **필수** `GET /v1/effects`에서 확인한, 공개된 고정 이펙트 ID입니다. --- `effect_version`   `integer`   **선택** 변경되지 않는 버전을 선택적으로 지정합니다. 생략하면 현재 공개 버전을 사용합니다. **범위:** x >= 1 --- `images`   `string[]`   **필수** 선택한 이펙트 버전이 요구하는 순서대로 나열한 공개 HTTPS 입력 이미지입니다. 정확한 개수와 허용되는 미디어 규칙은 `GET /v1/effects/{effect_id}`에서 확인하고, 로컬 파일은 `POST /v1/files`로 업로드하세요. **개수:** 1\~7개 --- `options`   `object`   **선택** 선택한 이펙트 버전이 지원하는 선택 제어 항목입니다. 지원하지 않는 항목은 생략하세요. 기준은 카탈로그입니다. --- `options.aspect_ratio`   `string`   **선택** 선택한 이펙트가 이 옵션을 제공할 때 요청하는 출력 화면비입니다. --- `options.resolution`   `string`   **선택** 선택한 이펙트가 이 옵션을 제공할 때 요청하는 출력 해상도입니다. --- `options.duration`   `integer`   **선택** 선택한 이펙트가 이 옵션을 제공할 때 요청하는 영상 길이(초)입니다. --- `options.bgm`   `boolean`   **선택** 선택한 이펙트가 지원하면 배경 음악을 포함합니다. --- `options.seed`   `integer`   **선택** 선택한 이펙트가 지원하면 결과를 재현할 수 있도록 시드를 선택적으로 지정합니다. ## 응답 요청에 성공하면 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`를 저장하고, `status`가 `succeeded` 또는 `failed`가 될 때까지 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`, 메시지에 원인이 표시됨). `Authorization: Bearer ` 형식으로 보내세요. 키는 `sk-` 접두사가 있어도 없어도 동작합니다. 재시도할 수 없습니다. | | `402` | 잔액이 부족합니다(`insufficient_credits`). 계정 잔액이 0이거나 이 요청의 가격보다 적습니다. 충전한 뒤 다시 보내세요. 충전 전에는 재시도할 수 없습니다. | | `403` | 이 키나 계정으로는 이 호출을 할 수 없습니다(`forbidden`). 예를 들어 무료 크레딧으로 쓸 수 없는 모델(충전하면 사용 가능), 키의 IP 허용 목록 밖에서 보낸 요청, 키의 그룹에 속하지 않은 모델이 해당합니다. 재시도할 수 없습니다. | | `404` | 이펙트 또는 요청한 버전을 사용할 수 없습니다(`not_found`). | | `409` | `Idempotency-Key`가 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를 반환하지 않습니다. |