Music API and CLI

Connect your account

1. Create an account and verify your email.
2. Open Settings and create an API key. API keys
3. Keep the key in your server or secret manager. Send it as an Authorization header, never in a URL or frontend code.

Keys expire after 90 days. You can have five active keys and revoke any key immediately in Settings. Read-only keys cannot generate songs.

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

Prepare, start and check your song

First prepare a brief without spending a credit. Starting that preparation uses one existing song credit. Keep the same request ID when retrying. A timeout must not start another song.

{
  "requestId": "my-first-song-20261021",
  "input": {
    "mode": "idea",
    "idea": "A hopeful song about starting over in a new city",
    "direction": "Warm acoustic pop, steady drums, gentle vocals",
    "language": "en",
    "duration": 120
  },
  "uiLocale": "en"
}

Send this JSON to POST /v1/songs/prepare. Then send its preparedRequestId to POST /v1/songs/start. Check GET /v1/jobs/{jobId} at least 15 seconds apart. When ready, open the returned private library link to listen or download.

Supported song languages are English, Spanish, German, French and Brazilian Portuguese. Request 60 to 180 seconds. Use lyrics mode for your own words, or instrumental: true for music without vocals.

API endpoints

The API base URL is https://mcp.wordsintomusic.com/v1. Download the OpenAPI specification for request fields, limits, permissions and response formats.

Use the command line

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

Use Node.js 22 or later. Pass the key to login through standard input, or supply WIM_API_KEY from your secret manager. Do not put it in command arguments or shell history. Run wim --help for details.

Credits, limits and privacy

API access and the CLI have no separate subscription. Generating a recording uses your existing song allowance, with the same account limits as the app. The API never buys credits or starts a subscription.

Only the key owner's songs can be read. Lyrics are returned only when requested. Revoking a key stops new API calls, while a song already accepted continues processing.

The gateway allows up to 30 API requests per minute per IP. API and MCP calls also share a 120-request account limit per minute. Honor Retry-After on a 429 response. Successful preparation IDs remain available for retry protection for 30 days after expiry.

For assistant connections, use our MCP setup guide. For account allowances, see Pricing.