빠른 시작

BeatAPI는 텍스트, 워크플로, 실시간, 영상, 이미지, 이펙트 API 전반에서 서버 측 API 키 하나를 사용합니다. 아래 세 단계로 시작한 다음, 동기식 텍스트 응답, 공통 작업 필드, 업로드, 제한, 운영 환경 오류는 이 가이드의 나머지 부분을 참고하세요.

세 단계로 첫 작업 만들기

1. API 키 만들기

대시보드 → API Keys에서 키를 만든 다음, 명령 기록에 남지 않도록 셸에 불러오세요.

read -rsp "BeatAPI API key: " BEATAPI_API_KEY && echo
export BEATAPI_API_KEY

모든 요청은 https://api.beatapi.io 기본 URL과 다음 헤더를 사용합니다.

Authorization: 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": "Editorial product photograph on a warm stone pedestal."
  }'

올바른 요청은 201 Created를 반환합니다. 반환된 data.id를 저장하세요.

3. 결과 폴링

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

task_8K2qA를 2단계의 data.id로 바꾸세요. 폴링 사이에는 data.poll_after_seconds만큼 기다리세요(이미지 5, 영상과 이펙트 8, 데이터와 워크플로 10. 작업이 실행되는 동안 표시됩니다). succeeded이면 data.output.media를 읽고 폴링을 멈추세요. failed이면 data.error_code와 data.error_message를 읽고 폴링을 멈추세요.

API 선택

텍스트 호출은 동기식으로 또는 서버 전송 이벤트 스트림으로 반환됩니다. 실시간 API는 수명이 짧은 세션을 만듭니다. 워크플로, 영상, 이미지, 이펙트 생성 작업은 비동기 작업을 반환합니다. data.id를 저장한 뒤 공통 작업 엔드포인트를 폴링하세요. GET /v1/tasks/{task_id} 폴링에는 요청 속도 제한이 없으며, 폴링 사이에 poll_after_seconds만큼 기다리세요.

GPT 모델 선택, 요청 형식, 스트리밍 예시는 GPT 가이드를 참고하세요.

작업 상태 조회

GET /v1/tasks/{task_id}

상태 값

이미지와 영상 작업은 queued, processing, succeeded, failed만 사용합니다. 나머지 상태는 뮤직비디오 전용입니다.

정규화된 작업 필드

사용량과 출력 필드

실패한 작업에서 usage.credits_reserved는 생성 시 보류된 금액, usage.credits_charged와 usage.credits_settled는 0, usage.credits_refunded는 환불된 금액입니다. 접수된 작업은 6가지 코드 중 하나로 실패합니다. content_policy_violation과 bad_request(재시도 불가), processing_unavailable, processing_timeout, processing_failed, result_transfer_failed(재시도 가능)입니다. 오류를 참고하세요.

입력 파일 업로드

POST /v1/files

입력이 공개 HTTPS URL에 없고 로컬에 있을 때 파일 업로드를 사용하세요. 모든 업로드에는 정확한 Content-Length가 있어야 합니다. 일반적인 curl, 브라우저, SDK 업로드는 자동으로 설정합니다. 길이를 선언하지 않은 청크 업로드는 본문을 버퍼링하기 전에 거부됩니다.

멀티파트 필드

curl https://api.beatapi.io/v1/files \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -F "file=@./song.mp3" \
  -F "purpose=input"

파일 본문을 해당 자산의 Content-Type과 함께 그대로 보낼 수도 있습니다.

흔히 쓰이는 일부 별칭은 받아서 표준 형식으로 저장합니다. 예를 들어 image/jpg는 image/jpeg으로, audio/mp3는 audio/mpeg로, text/plain(.srt 파일 이름)은 application/x-subrip으로 저장합니다. PDF, 일반 텍스트, octet-stream, 지원하지 않는 영상 컨테이너, ZIP 업로드는 400 bad_request로 거부됩니다. 게이트웨이는 선언된 Content-Type을 신뢰하며, 파일 이름에 확장자가 있으면 그 형식과 일치해야 합니다. 파일 내용은 검사하지 않으며 길이나 크기도 읽지 않습니다. 업로드에서 받은 파일이라도 작업을 만들 때 그 파일을 쓰는 모델이나 워크플로가 길이나 크기 규칙 등으로 거부할 수 있습니다. 워크플로 입력 URL은 localhost, 사설 네트워크 또는 데이터 URL일 수 없습니다.

업로드 거부는 다음 메시지 중 하나와 함께 400 bad_request로 반환됩니다.

파일을 저장할 수 없으면 업로드는 processing_unavailable(“File storage is temporarily unavailable. Retry later; nothing was stored.”) 또는 result_transfer_failed(“The file could not be stored on our side. Retry; nothing was stored.”)와 함께 503으로 응답합니다. 백오프를 두고 재시도하세요.

파일 응답

{
  "data": {
    "id": "file_6f1c2b9e-4d0a-4c58-9a57-2f0a8f3d7b11",
    "object": "file",
    "url": "https://files.beatapi.io/u/6f1c2b9e4d0a4c589a572f0a8f3d7b11.mp3",
    "key": "u/6f1c2b9e4d0a4c589a572f0a8f3d7b11.mp3",
    "mime_type": "audio/mpeg",
    "size_bytes": 1048576,
    "purpose": "input",
    "created_at": 1782210000
  }
}

모델이나 워크플로 요청에는 data.url을 사용하세요. 모델이나 워크플로는 작업을 만들 때 자체 제한을 검사합니다. 예를 들어 Standard 뮤직비디오는 10180초, Premium은 10300초 길이의 오디오를 받습니다.

사용량과 한도 확인

GET /v1/usage

API 키나 계정의 개인 액세스 토큰을 보내세요. 둘 다 같은 계정 전체 요약을 반환합니다.

유일한 선택 쿼리 파라미터 period는 집계와 세부 내역의 기간(현재 시점까지)을 정합니다: 24h, 7d, 30d 또는 all(기본값, 계정 전체 기록). credit_balance와 concurrency는 항상 현재 값입니다. 그 밖의 파라미터나 다른 period 값은 400으로 거부됩니다.

curl "https://api.beatapi.io/v1/usage?period=7d" \
  -H "Authorization: Bearer $BEATAPI_API_KEY"

세부 항목 필드:

storyboard_ready 또는 requires_action에서 일시 중지된 뮤직비디오 작업은 처리 중 작업으로 집계되지 않으면서도 정산된 크레딧이 있을 수 있습니다.

작업이나 텍스트 요청별 비용은 계정의 개인 액세스 토큰으로 요청별 사용 기록을 읽어 확인하세요.

오류와 재시도 정책

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: at most 60 successful requests per 1 minute(s). Retry after 60 seconds.",
    "retryable": true,
    "request_id": "req_abc123",
    "retry_after_seconds": 60
  }
}

모든 오류에는 code, 원인을 설명하는 영어 message, request_id가 있습니다. 429 rate_limit_exceeded에만 retry_after_seconds와 Retry-After 헤더가 추가로 있으며, 503은 대기 시간을 알 수 없으므로 백오프를 두고 재시도하세요. 아래 표의 모든 코드에는 retryable이 있습니다. 이 값으로 분기하세요. false는 요청을 바꾸기 전까지 같은 호출이 다시 실패한다는 뜻입니다.

공개 오류 코드

BeatAPI는 아래의 고정된 공개 코드만 노출합니다. BeatAPI는 모델 뒤의 공급사를 밝히지 않으며 원본 응답 본문을 그대로 전달하지 않습니다. 오류 페이지에서 작업 생성 시와 접수된 작업에서 각 실패가 어떤 코드를 내는지, 텍스트 엔드포인트가 모델 호출 전(이 형식)과 호출 중(SDK 고유의 오류 형식. BeatAPI 자체 거부에는 BeatAPI 코드, 모델 측 실패에는 변환된 코드)에 어떻게 실패하는지 확인할 수 있습니다. 이 값은 응답의 error.code에 나타납니다. 비동기 작업이 최종 실패하면 작업의 error_code에도 해당 값이 반환될 수 있습니다.

BeatAPI는 502나 504로 응답하지 않습니다. 이런 응답을 받았다면 네트워크 에지에서 온 것이며 JSON 본문이 없으므로 503처럼 재시도하세요.

멱등성:

• 워크플로, 이미지, 영상, 이펙트 작업 생성과 POST /v1/capabilities/run은 선택적으로 키를 받습니다. 실시간 세션 생성에는 키가 필수입니다(최대 255자).
• 키는 24시간 동안 기억됩니다. 255자를 넘는 키는 400 bad_request입니다.
• 같은 키를 다른 본문이나 경로에 사용하면 409 idempotency_conflict입니다. 첫 요청이 아직 처리 중일 때 같은 키를 사용해도 마찬가지입니다.
• 완전히 같은 요청을 반복하면 Idempotent-Replayed: true 헤더와 함께 저장된 응답이 반환됩니다.
• 2xx 응답만 저장되므로 400이나 402 뒤에는 같은 키로 재시도할 수 있습니다.

운영 환경 체크리스트

• 정확한 https://api.beatapi.io 오리진을 사용하세요.
• 영구 API 키는 신뢰할 수 있는 서버에만 두세요.
• 선택한 API 페이지에 따라 필수/선택 필드, 열거값, 제한, 조건부 규칙을 검증하세요.
• 백그라운드 작업을 시작하기 전에 작업/세션 ID와 request_id를 저장하세요.
• poll_after_seconds마다 폴링하고, 문서에 나온 종료 상태나 조치 필요 상태에서 멈추세요.
• 보관해야 하는 결과는 내려받아 저장하세요.
• 상태 코드, Retry-After, retry_after_seconds를 따르세요.
• JSON을 파싱하기 전에 원본 바이트로 웹훅 서명을 검증하세요. 웹훅은 task.succeeded와 task.failed만 보내며 3번 시도합니다(1분 후와 5분 후 재시도). 시간 초과 정리로 실패 처리된 작업은 이벤트를 보내지 않으므로, 폴링을 기준으로 삼으세요.
• 크레딧 보류, 정산, 환불, 오류, 최종 출력 URL을 기록하세요.
• 카메라, 얼굴, 음성, 참조 자료를 처리하기 전에 개인정보처리방침과 서비스 약관을 검토하세요.