# API e CLI musicali > Trasforma un'idea o i tuoi testi in una canzone dai tuoi script. Usa lo stesso account, crediti e libreria privata dell'app. [llms.txt](https://wordsintomusic.com/it/developers/llms.txt) ## Collega il tuo account [Crea un account](https://wordsintomusic.com/create/) e verifica la tua email. Apri Impostazioni e crea una chiave API. [Chiavi API](https://wordsintomusic.com/app/settings/) Conserva la chiave nel tuo server o gestore di segreti. Inviala come header di autorizzazione, mai in un URL o codice frontend. Le chiavi scadono dopo 90 giorni. Puoi avere cinque chiavi attive e revocare qualsiasi chiave immediatamente nelle Impostazioni. Le chiavi di sola lettura non possono generare canzoni. ```bash curl https://mcp.wordsintomusic.com/v1/account \ -H "Authorization: Bearer $WIM_API_KEY" ``` ## Prepara, avvia e controlla la tua canzone Per prima cosa, prepara un brief senza spendere un credito. L'avvio di tale preparazione utilizza un credito canzone esistente. Mantieni lo stesso ID richiesta quando riprovi. Un timeout non deve avviare un'altra canzone. Invia questo JSON a POST /v1/songs/prepare. Poi invia il suo preparedRequestId a POST /v1/songs/start. Controlla GET /v1/jobs/{jobId} con un intervallo di almeno 15 secondi. Quando è pronto, apri il link della libreria privata restituito per ascoltare o scaricare. Le lingue supportate per le canzoni sono inglese, spagnolo, tedesco, francese, portoghese brasiliano, italiano, olandese, polacco, svedese, giapponese e coreano. Richiedi una durata da 60 a 180 secondi. Usa la modalità lyrics per il tuo testo, oppure instrumental: true per musica senza voci. ```json { "requestId": "my-first-song-20261021", "input": { "mode": "idea", "idea": "Una canzone piena di speranza sul ricominciare in una nuova città", "direction": "Pop acustico caldo, batteria costante, voci delicate", "language": "it", "duration": 120 }, "uiLocale": "it" } ``` ## Endpoint API L'URL base dell'API è `https://mcp.wordsintomusic.com/v1`. [Scarica la specifica OpenAPI](https://wordsintomusic.com/it/openapi.json) per campi di richiesta, limiti, permessi e formati di risposta. | Metodo e percorso | Azione | | --- | --- | | `GET /v1/account` | Controlla i tuoi crediti canzone disponibili | | `POST /v1/billing/checkout` | Crea un link di checkout Stripe | | `POST /v1/songs/prepare` | Prepara una canzone senza spendere un credito | | `POST /v1/songs/start` | Genera la canzone preparata usando un credito esistente | | `GET /v1/jobs/{jobId}` | Controlla lo stato di generazione | | `GET /v1/songs` | Elenca la tua libreria di canzoni privata | | `GET /v1/songs/{id}` | Leggi una delle tue canzoni | https://mcp.wordsintomusic.com/v1 [Scarica la specifica OpenAPI](https://wordsintomusic.com/openapi.json) ## API OAuth per le app collegate Zapier e le altre app collegate usano OAuth 2.0 invece di una chiave API. L'utente accede a Words into Music e approva ogni autorizzazione. Poi l'app invia richieste JSON a un unico endpoint HTTPS. ```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 ``` Usa il flusso con codice di autorizzazione e PKCE S256. I token di accesso scadono dopo 15 minuti. Per rinnovarne uno, invia grant_type=refresh_token, il token di aggiornamento e il tuo client_id all'URL del token. Ogni rinnovo restituisce un nuovo token di aggiornamento, valido per 30 giorni. Invia il token di accesso nell'header Authorization: Bearer, con Content-Type: application/json e Accept: application/json, text/event-stream. Ogni richiesta è un messaggio JSON-RPC 2.0 tools/call che indica un'operazione e i suoi argomenti. ```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"] } } } ``` I dati si trovano in result.structuredContent. I campi corrispondono alla risposta REST della stessa azione nella specifica OpenAPI. Un'operazione non riuscita restituisce result.isError: true con un codice di errore. Un token di accesso mancante o scaduto restituisce 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 restituisce fino a 20 canzoni per richiesta, dalla più recente. Passa il cursor restituito per leggere la pagina successiva. Un cursor null indica che non ci sono altre canzoni. createdAt è espresso in millisecondi Unix. L'url apre la pagina privata della canzone nella libreria, e il proprietario deve accedere per vederla. | Operazione | Autorizzazione | Azione | | --- | --- | --- | | `get_account_usage` | `account:read` | Controlla i tuoi crediti canzone disponibili | | `list_songs` | `songs:read` | Elenca la tua libreria di canzoni privata | | `get_song` | `songs:read` | Leggi una delle tue canzoni | | `get_song_job` | `songs:read` | Controlla lo stato di generazione | | `prepare_song` | `songs:create` | Prepara una canzone senza spendere un credito | | `start_song` | `songs:create` | Genera la canzone preparata usando un credito esistente | | `create_checkout_link` | `songs:create` | Crea un link di checkout Stripe | L'integrazione con Zapier usa due operazioni. Il test di connessione chiama get_account_usage e assegna alla connessione il nome accountReference, un codice stabile che non rivela l'indirizzo email né l'ID dell'account. Il trigger New Song chiama list_songs con limit 20 e segue il cursor per un massimo di cinque pagine. Le richieste OAuth rientrano nello stesso limite di account di 120 richieste al minuto delle chiavi API. Leggere l'utilizzo dell'account o la libreria delle canzoni non consuma crediti. ## Usa la riga di comando Usa Node.js 22 o versioni successive. Passa la chiave per il login tramite input standard, o fornisci WIM_API_KEY dal tuo gestore di segreti. Non inserirla negli argomenti del comando o nella cronologia della shell. Esegui wim --help per i dettagli. ```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 ``` ## Crediti, limiti e privacy Se hai bisogno di crediti canzone, l'API restituisce HTTP 402. Scegli un'offerta da GET /v1/account, poi POST /v1/billing/checkout con la tua scelta confermata. Paga su Stripe senza un altro login al sito web. Controlla il tuo saldo e riprova con il preparedRequestId originale dopo che il pagamento è stato confermato. L'accesso API e la CLI non hanno un abbonamento separato. La generazione di una registrazione utilizza la tua quota di canzoni esistente, con gli stessi limiti dell'account dell'app. L'API non ti addebita mai automaticamente. Possono essere lette solo le canzoni del proprietario della chiave. I testi vengono restituiti solo quando richiesto. La revoca di una chiave interrompe le nuove chiamate API, mentre una canzone già accettata continua l'elaborazione. Il gateway consente fino a 30 richieste API al minuto per IP. Le chiamate API e MCP condividono anche un limite di account di 120 richieste al minuto. Rispetta Retry-After su una risposta 429. Gli ID di preparazione riusciti rimangono disponibili per la protezione dai tentativi per 30 giorni dopo la scadenza. Per le connessioni assistente, usa il nostro [Guida all'installazione MCP](https://wordsintomusic.com/it/mcp/). Per le quote dell'account, vedi [Prezzi](https://wordsintomusic.com/it/pricing/).