이펙트 API

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

버전이 지정된 BeatAPI 이펙트로 비동기 이미지 또는 영상 이펙트 작업을 생성합니다.

인증

Authorization   string   필수

BeatAPI API 키를 Bearer 토큰으로 보내세요. 키는 대시보드에서 만들 수 있습니다.

Authorization: Bearer <BEATAPI_API_KEY>

영구 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을 반환합니다.

{
  "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에서 읽습니다.

오류