# 음악 API 및 CLI

> 자신의 스크립트를 사용하여 아이디어나 가사를 노래로 만들어 보세요. 앱과 동일한 계정, 크레딧, 비공개 라이브러리를 사용해요.

[llms.txt](https://wordsintomusic.com/ko/developers/llms.txt)

## 계정 연결

[계정 생성](https://wordsintomusic.com/create/) 후 이메일을 인증해 보세요.

설정을 열고 API 키를 생성해 보세요. [API 키](https://wordsintomusic.com/app/settings/)

키는 서버나 비밀 관리자에 보관하세요. URL이나 프런트엔드 코드에 넣지 말고, Authorization 헤더로 전송하세요.

키는 90일 후에 만료돼요. 최대 5개의 활성 키를 가질 수 있으며, 설정에서 언제든지 키를 즉시 폐기할 수 있어요. 읽기 전용 키로는 곡을 생성할 수 없어요.

```bash
curl https://mcp.wordsintomusic.com/v1/account \
  -H "Authorization: Bearer $WIM_API_KEY"
```

## 곡 준비, 시작 및 확인

먼저 크레딧을 사용하지 않고 브리프를 준비해 보세요. 준비를 시작하면 기존 곡 크레딧 하나가 사용돼요. 재시도 시에는 동일한 요청 ID를 유지하세요. 타임아웃으로 인해 다른 곡이 시작되어서는 안 돼요.

이 JSON을 POST /v1/songs/prepare로 전송하세요. 그런 다음 해당 preparedRequestId를 POST /v1/songs/start로 전송하세요. GET /v1/jobs/{jobId}를 최소 15초 간격으로 확인해 보세요. 준비가 완료되면 반환된 비공개 라이브러리 링크를 열어 듣거나 다운로드해 보세요.

지원하는 곡 언어는 영어, 스페인어, 독일어, 프랑스어, 브라질 포르투갈어, 이탈리아어, 네덜란드어, 폴란드어, 스웨덴어, 일본어, 한국어입니다. 길이는 60~180초로 요청하세요. 직접 쓴 가사를 쓰려면 가사 모드를, 보컬 없는 음악을 만들려면 instrumental: true를 사용하세요.

```json
{
  "requestId": "my-first-song-20261021",
  "input": {
    "mode": "idea",
    "idea": "새로운 도시에서 다시 시작하는 것에 대한 희망찬 노래",
    "direction": "따뜻한 어쿠스틱 팝, 안정적인 드럼, 부드러운 보컬",
    "language": "ko",
    "duration": 120
  },
  "uiLocale": "ko"
}
```

## API 엔드포인트

API 기본 URL은 다음과 같아요 `https://mcp.wordsintomusic.com/v1`. [OpenAPI 사양 다운로드](https://wordsintomusic.com/ko/openapi.json) 요청 필드, 제한, 권한 및 응답 형식에 대한 정보예요.

| 메서드 및 경로 | 작업 |
| --- | --- |
| `GET /v1/account` | 사용 가능한 곡 크레딧 확인 |
| `POST /v1/billing/checkout` | Stripe 결제 링크 생성 |
| `POST /v1/songs/prepare` | 크레딧을 사용하지 않고 곡 준비 |
| `POST /v1/songs/start` | 기존 크레딧 하나를 사용하여 준비된 곡 생성 |
| `GET /v1/jobs/{jobId}` | 생성 상태 확인 |
| `GET /v1/songs` | 비공개 곡 라이브러리 목록 보기 |
| `GET /v1/songs/{id}` | 내 곡 중 하나 읽기 |

https://mcp.wordsintomusic.com/v1

[OpenAPI 사양 다운로드](https://wordsintomusic.com/openapi.json)

## 연결된 앱용 OAuth API

Zapier 같은 연결된 앱은 API 키 대신 OAuth 2.0을 사용해요. 사용자가 Words into Music에 로그인하고 각 권한을 승인해요. 그다음 앱이 하나의 HTTPS 엔드포인트로 JSON 요청을 보내요.

```http
Authorization URL  GET   https://mcp.wordsintomusic.com/authorize
Token URL          POST  https://mcp.wordsintomusic.com/token
API endpoint       POST  https://mcp.wordsintomusic.com/mcp
Discovery          GET   https://mcp.wordsintomusic.com/.well-known/oauth-authorization-server
Scopes             account:read songs:read songs:create offline_access
```

S256 PKCE를 사용하는 인증 코드 흐름을 사용하세요. 액세스 토큰은 15분 후 만료돼요. 토큰을 갱신하려면 grant_type=refresh_token, 리프레시 토큰, client_id를 토큰 URL로 보내세요. 갱신할 때마다 30일 동안 유효한 새 리프레시 토큰이 반환돼요.

액세스 토큰은 Authorization: Bearer 헤더로 보내고, Content-Type: application/json과 Accept: application/json, text/event-stream을 함께 지정하세요. 각 요청은 하나의 작업과 인수를 지정하는 JSON-RPC 2.0 tools/call 메시지예요.

```http
POST https://mcp.wordsintomusic.com/mcp
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_account_usage",
    "arguments": {}
  }
}

HTTP/1.1 200 OK
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"accountReference\":\"WIM-3F9A1C07B2D4\",\"availableSongs\":4,\"reservedSongs\":0,\"songCreditCost\":1,\"accountUrl\":\"https://wordsintomusic.com/app/songs/\",\"supportedLanguages\":[\"en\",\"es\",\"de\",\"fr\",\"pt-BR\",\"it\",\"nl\",\"pl\",\"sv\",\"ja\",\"ko\"]}"
      }
    ],
    "structuredContent": {
      "accountReference": "WIM-3F9A1C07B2D4",
      "availableSongs": 4,
      "reservedSongs": 0,
      "songCreditCost": 1,
      "accountUrl": "https://wordsintomusic.com/app/songs/",
      "supportedLanguages": ["en", "es", "de", "fr", "pt-BR", "it", "nl", "pl", "sv", "ja", "ko"]
    }
  }
}
```

데이터는 result.structuredContent에 있어요. 필드는 OpenAPI 사양에 있는 같은 작업의 REST 응답과 같아요. 실패한 작업은 오류 코드와 함께 result.isError: true를 반환해요. 액세스 토큰이 없거나 만료되면 HTTP 401을 반환해요.

```http
POST https://mcp.wordsintomusic.com/mcp
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_songs",
    "arguments": {
      "limit": 20
    }
  }
}

HTTP/1.1 200 OK
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"songs\":[{\"id\":\"sample-song-a1b2c3\",\"title\":\"Sample Song\",\"language\":\"en\",\"duration\":120,\"createdAt\":1792488600000,\"favorite\":false,\"url\":\"https://wordsintomusic.com/app/songs/sample-song-a1b2c3/\"}],\"cursor\":null}"
      }
    ],
    "structuredContent": {
      "songs": [
        {
          "id": "sample-song-a1b2c3",
          "title": "Sample Song",
          "language": "en",
          "duration": 120,
          "createdAt": 1792488600000,
          "favorite": false,
          "url": "https://wordsintomusic.com/app/songs/sample-song-a1b2c3/"
        }
      ],
      "cursor": null
    }
  }
}
```

list_songs는 요청당 최대 20곡을 최신순으로 반환해요. 반환된 cursor를 전달하면 다음 페이지를 읽을 수 있어요. cursor가 null이면 더 이상 곡이 없다는 뜻이에요. createdAt은 Unix 밀리초 단위예요. url은 곡의 비공개 라이브러리 페이지를 열며, 보려면 소유자가 로그인해야 해요.

| 작업 | 권한 | 작업 |
| --- | --- | --- |
| `get_account_usage` | `account:read` | 사용 가능한 곡 크레딧 확인 |
| `list_songs` | `songs:read` | 비공개 곡 라이브러리 목록 보기 |
| `get_song` | `songs:read` | 내 곡 중 하나 읽기 |
| `get_song_job` | `songs:read` | 생성 상태 확인 |
| `prepare_song` | `songs:create` | 크레딧을 사용하지 않고 곡 준비 |
| `start_song` | `songs:create` | 기존 크레딧 하나를 사용하여 준비된 곡 생성 |
| `create_checkout_link` | `songs:create` | Stripe 결제 링크 생성 |

Zapier 연동은 두 가지 작업을 사용해요. 연결 테스트는 get_account_usage를 호출하고 accountReference로 연결에 라벨을 붙여요. 이 값은 이메일 주소나 계정 ID를 드러내지 않는 고정 코드예요. New Song 트리거는 limit 20으로 list_songs를 호출하고 cursor를 따라 최대 5페이지까지 읽어요.

OAuth 요청은 API 키와 같은 분당 120개 요청의 계정 제한에 포함돼요. 계정 사용량이나 곡 라이브러리를 읽어도 크레딧은 사용되지 않아요.

## 명령줄 사용

Node.js 22 이상을 사용하세요. 표준 입력을 통해 로그인 키를 전달하거나, 비밀 관리자에서 WIM_API_KEY를 제공하세요. 명령 인자나 셸 기록에 키를 넣지 마세요. 자세한 내용은 wim --help를 실행해 보세요.

```bash
npm install -g words-into-music-cli
wim login --key-stdin
wim account
wim prepare --file brief.json
wim start PREPARED_REQUEST_ID --confirm
wim job JOB_ID
wim songs --limit 10
```

## 크레딧, 제한 및 개인 정보 보호

곡 크레딧이 필요한 경우 API는 HTTP 402를 반환해요. GET /v1/account에서 제안을 선택한 다음, 확인된 선택 사항으로 POST /v1/billing/checkout을 호출하세요. 다른 웹사이트 로그인 없이 Stripe에서 결제하세요. 결제가 확인된 후 잔액을 확인하고 원래 preparedRequestId로 다시 시도해 보세요.

API 접근 및 CLI에는 별도의 구독이 없어요. 녹음을 생성하는 것은 앱과 동일한 계정 제한 내에서 기존 곡 허용량을 사용해요. API는 자동으로 요금을 청구하지 않아요.

키 소유자의 곡만 읽을 수 있어요. 가사는 요청 시에만 반환돼요. 키를 폐기하면 새로운 API 호출은 중단되지만, 이미 승인된 곡은 계속 처리돼요.

게이트웨이는 IP당 분당 최대 30개의 API 요청을 허용해요. API 및 MCP 호출은 또한 분당 120개 요청의 계정 제한을 공유해요. 429 응답 시 Retry-After를 준수하세요. 성공적인 준비 ID는 만료 후 30일 동안 재시도 보호를 위해 계속 사용할 수 있어요.

어시스턴트 연결의 경우, 다음을 사용하세요 [MCP 설정 가이드](https://wordsintomusic.com/ko/mcp/). 계정 허용량은 다음을 참조하세요 [가격](https://wordsintomusic.com/ko/pricing/).