API e CLI musicali

Collega il tuo account

1. Crea un account e verifica la tua email.
2. Apri Impostazioni e crea una chiave API. Chiavi API
3. 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.

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.

{
  "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"
}

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.

Endpoint API

L'URL base dell'API è https://mcp.wordsintomusic.com/v1. Scarica la specifica OpenAPI per campi di richiesta, limiti, permessi e formati di risposta.

Usa la riga di comando

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

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.

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. Per le quote dell'account, vedi Prezzi.