> 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.

# BeatAPI Workflow API

> 작업, 폴링, 서명된 웹훅으로 Music Video, Ecommerce Video, Video Analysis 워크플로를 구축합니다.

# Workflow API

단일 모델의 계약이 아니라 안정적인 BeatAPI 기능이 필요할 때 Workflow API를 사용하세요.

| 워크플로 ID           | 필수 입력                                 | 주요 제어                                               | 결과                            |
| ----------------- | ------------------------------------- | --------------------------------------------------- | ----------------------------- |
| `music-video`     | 오디오와 등급별 시각 참조                        | Standard/Premium 등급, 품질, 해상도, 모드, 자막, 립싱크, 검토/편집/합성 | 호스팅된 Music Video와 스토리보드 메타데이터 |
| `ecommerce-video` | 제품 이미지 1–7장과 10–60초 길이                | 프롬프트, 화면비, 언어                                       | 호스팅된 1080p 제품 영상              |
| `video-analysis`  | `/v1/files`로 업로드한 MP4 또는 MOV 하나와 프롬프트 | Standard/deep 깊이와 출력 토큰 한도                          | 분석 텍스트와 토큰 사용량                |

두 워크플로 모두 비동기 방식입니다:

1. 작업을 만들고 `data.id`를 저장하세요.
2. 5\~10초마다 `GET /v1/tasks/{task_id}`를 폴링하세요.
3. `succeeded` 또는 `failed`에서 멈추세요. Music Video 수동 검토는 `requires_action`에서 일시 정지될 수 있습니다.
4. 폴링이 동작한 뒤 알림용으로 서명된 [웹훅](/webhooks)을 사용하세요.

필드 단위 전체 계약은 [Music Video](/workflow-api/music-video), [Ecommerce Video](/workflow-api/ecommerce-video), [Video Analysis](/workflow-api/video-analysis)를 참고하세요.

## 워크플로 종류 목록

`GET /v1/workflows`

이 공개 엔드포인트는 파라미터가 없으며 인증이 필요하지 않습니다.

```bash
curl https://api.beatapi.io/v1/workflows
```

```json
{
  "data": {
    "object": "list",
    "data": [
      {
        "id": "music-video",
        "object": "workflow",
        "name": "Music Video API",
        "description": "Generate short music video clips from audio, lyrics, and visual direction."
      },
      {
        "id": "ecommerce-video",
        "object": "workflow",
        "name": "Ecommerce Video API",
        "description": "Generate product ad videos from product images and a short creative brief."
      },
      {
        "id": "video-analysis",
        "object": "workflow",
        "name": "Video Analysis API",
        "description": "Analyze an uploaded video with timestamp-aware multimodal reasoning."
      }
    ]
  }
}
```

| 필드                        | 타입        | 의미                                                   |
| ------------------------- | --------- | ---------------------------------------------------- |
| `data.object`             | string    | `list`                                               |
| `data.data`               | object\[] | 사용 가능한 출시 워크플로                                       |
| `data.data[].id`          | string    | `music-video`, `ecommerce-video` 또는 `video-analysis` |
| `data.data[].object`      | string    | `workflow`                                           |
| `data.data[].name`        | string    | 표시 이름                                                |
| `data.data[].description` | string    | 워크플로 요약                                              |

`429 rate_limit_exceeded`에는 `Retry-After`와 `error.retry_after_seconds`가 포함될 수 있습니다. 재시도 전에 최소 그만큼 기다리세요.

## 공통 운영 규칙

* Base URL: `https://api.beatapi.io`.
* 영구 API 키는 신뢰할 수 있는 서버에 보관하세요.
* 입력은 공개되어 접근 가능해야 합니다. 로컬 자산에는 `POST /v1/files`를 사용하세요.
* 생성 요청은 크레딧을 보류하고 정규화된 작업 객체를 반환합니다.
* `request_id`, 사용량, 상태, 오류, 최종 출력 URL을 기록하세요.
* 문서화된 멱등성 헤더가 없는 불확실한 생성 요청은 무작정 재시도하지 마세요.

생성 작업 하나만 필요하고 모델을 직접 고르고 싶다면 모델 단위의 [Video API](/video-api) 또는 [Image API](/image-api)를 선택하세요.