# Muziek-API en CLI > Verander een idee of je teksten in een nummer vanuit je eigen scripts. Gebruik hetzelfde account, credits en privébibliotheek als de app. [llms.txt](https://wordsintomusic.com/nl/developers/llms.txt) ## Verbind je account [Maak een account aan](https://wordsintomusic.com/create/) en verifieer je e-mail. Open Instellingen en maak een API-sleutel aan. [API-sleutels](https://wordsintomusic.com/app/settings/) Bewaar de sleutel op je server of in je secret manager. Stuur deze als een Authorization header, nooit in een URL of frontend code. Sleutels verlopen na 90 dagen. Je kunt vijf actieve sleutels hebben en elke sleutel direct intrekken in Instellingen. Alleen-lezen sleutels kunnen geen nummers genereren. ```bash curl https://mcp.wordsintomusic.com/v1/account \ -H "Authorization: Bearer $WIM_API_KEY" ``` ## Je nummer voorbereiden, starten en controleren Bereid eerst een briefing voor zonder een credit uit te geven. Het starten van die voorbereiding gebruikt één bestaande nummercredit. Gebruik dezelfde aanvraag-ID bij een nieuwe poging. Een time-out mag geen ander nummer starten. Stuur deze JSON naar POST /v1/songs/prepare. Stuur vervolgens de preparedRequestId naar POST /v1/songs/start. Controleer GET /v1/jobs/{jobId} met een tussenpoos van minimaal 15 seconden. Zodra het klaar is, open je de ontvangen link naar je privébibliotheek om te luisteren of te downloaden. Ondersteunde songtalen zijn Engels, Spaans, Duits, Frans, Braziliaans Portugees, Italiaans, Nederlands, Pools, Zweeds, Japans en Koreaans. Vraag een lengte van 60 tot 180 seconden aan. Gebruik de songtekstmodus voor je eigen tekst, of instrumental: true voor muziek zonder zang. ```json { "requestId": "my-first-song-20261021", "input": { "mode": "idea", "idea": "Een hoopvol nummer over opnieuw beginnen in een nieuwe stad", "direction": "Warme akoestische pop, stabiele drums, zachte zang", "language": "nl", "duration": 120 }, "uiLocale": "nl" } ``` ## API-eindpunten De basis-URL van de API is `https://mcp.wordsintomusic.com/v1`. [Download de OpenAPI-specificatie](https://wordsintomusic.com/nl/openapi.json) voor aanvraagvelden, limieten, machtigingen en antwoordformaten. | Methode en pad | Actie | | --- | --- | | `GET /v1/account` | Controleer je beschikbare nummercredits | | `POST /v1/billing/checkout` | Maak een Stripe-betaallink aan | | `POST /v1/songs/prepare` | Bereid een nummer voor zonder een credit uit te geven | | `POST /v1/songs/start` | Genereer het voorbereide nummer met één bestaande credit | | `GET /v1/jobs/{jobId}` | Controleer de generatiestatus | | `GET /v1/songs` | Toon je privé nummerbibliotheek | | `GET /v1/songs/{id}` | Lees een van je nummers | https://mcp.wordsintomusic.com/v1 [Download de OpenAPI-specificatie](https://wordsintomusic.com/openapi.json) ## OAuth-API voor gekoppelde apps Zapier en andere gekoppelde apps gebruiken OAuth 2.0 in plaats van een API-sleutel. De gebruiker logt in bij Words into Music en keurt elke toestemming goed. Daarna stuurt de app JSON-aanvragen naar één HTTPS-endpoint. ```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 ``` Gebruik de authorization code flow met S256 PKCE. Toegangstokens verlopen na 15 minuten. Om er een te vernieuwen, stuur je grant_type=refresh_token, het vernieuwingstoken en je client_id naar de token-URL. Elke vernieuwing geeft een nieuw vernieuwingstoken terug dat 30 dagen geldig is. Stuur het toegangstoken in de header Authorization: Bearer, met Content-Type: application/json en Accept: application/json, text/event-stream. Elke aanvraag is een JSON-RPC 2.0-bericht tools/call dat één bewerking en de argumenten ervan noemt. ```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"] } } } ``` De gegevens staan in result.structuredContent. De velden komen overeen met het REST-antwoord voor dezelfde actie in de OpenAPI-specificatie. Een mislukte bewerking geeft result.isError: true terug met een foutcode. Een ontbrekend of verlopen toegangstoken geeft HTTP 401 terug. ```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 geeft maximaal 20 nummers per aanvraag terug, nieuwste eerst. Geef de teruggegeven cursor mee om de volgende pagina te lezen. Een cursor met null betekent dat er geen nummers meer zijn. createdAt staat in Unix-milliseconden. De url opent de privé bibliotheekpagina van het nummer, waarvoor de eigenaar moet inloggen. | Bewerking | Toestemming | Actie | | --- | --- | --- | | `get_account_usage` | `account:read` | Controleer je beschikbare nummercredits | | `list_songs` | `songs:read` | Toon je privé nummerbibliotheek | | `get_song` | `songs:read` | Lees een van je nummers | | `get_song_job` | `songs:read` | Controleer de generatiestatus | | `prepare_song` | `songs:create` | Bereid een nummer voor zonder een credit uit te geven | | `start_song` | `songs:create` | Genereer het voorbereide nummer met één bestaande credit | | `create_checkout_link` | `songs:create` | Maak een Stripe-betaallink aan | De Zapier-integratie gebruikt twee bewerkingen. De verbindingstest roept get_account_usage aan en geeft de verbinding een label met accountReference, een vaste code die het e-mailadres en de account-ID niet prijsgeeft. De trigger New Song roept list_songs aan met limit 20 en volgt de cursor over maximaal vijf pagina's. OAuth-aanvragen tellen mee voor dezelfde accountlimiet van 120 aanvragen per minuut als API-sleutels. Het accountgebruik of de nummerbibliotheek opvragen kost geen credits. ## Gebruik de commandoregel Gebruik Node.js 22 of nieuwer. Geef de sleutel door voor het inloggen via standaardinvoer, of lever de WIM_API_KEY aan vanuit je secret manager. Plaats deze niet in commandoargumenten of shellgeschiedenis. Voer wim --help uit voor details. ```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 ``` ## Credits, limieten en privacy Als je nummercredits nodig hebt, retourneert de API HTTP 402. Kies een aanbod uit GET /v1/account, stuur dan POST /v1/billing/checkout met je bevestigde keuze. Betaal op Stripe zonder opnieuw in te loggen op een andere website. Controleer je saldo en probeer de originele preparedRequestId opnieuw nadat de betaling is bevestigd. API-toegang en de CLI hebben geen apart abonnement. Het genereren van een opname gebruikt je bestaande nummertegoed, met dezelfde accountlimieten als de app. De API brengt je nooit automatisch kosten in rekening. Alleen de nummers van de sleuteleigenaar kunnen worden gelezen. Songteksten worden alleen teruggestuurd wanneer aangevraagd. Het intrekken van een sleutel stopt nieuwe API-aanroepen, terwijl een reeds geaccepteerd nummer wel wordt verwerkt. De gateway staat maximaal 30 API-aanvragen per minuut per IP toe. API- en MCP-aanroepen delen ook een accountlimiet van 120 aanvragen per minuut. Respecteer Retry-After bij een 429-antwoord. Succesvolle voorbereidings-ID's blijven 30 dagen na afloop beschikbaar voor bescherming bij herhaalpogingen. Voor assistent-verbindingen, gebruik onze [MCP installatiegids](https://wordsintomusic.com/nl/mcp/). Voor accounttegoeden, zie [Prijzen](https://wordsintomusic.com/nl/pricing/).