API Colora

L'API è la stessa API /v1 dell'app resa accessibile tramite chiavi API: le stesse pagine, personaggi, libri, crediti e limiti. Le chiavi API sono incluse nei piani Creator e Pro. Gli assistenti AI dovrebbero usare invece il connettore MCP.

URL base: https://colora-api.norvane-studio.com
OpenAPI 3.1: /openapi.json
MCP: https://colora-api.norvane-studio.com/mcp (OAuth)

Autenticazione

Crea una chiave nell'app in Account → Chiavi API e inviala come bearer token:

curl https://colora-api.norvane-studio.com/v1/me \
  -H "Authorization: Bearer co_live_..."

Crea un disegno

curl -X POST https://colora-api.norvane-studio.com/v1/pages \
  -H "Authorization: Bearer co_live_..." -H "Content-Type: application/json" \
  -d '{"subject": "un drago amichevole che legge un libro", "level": "kids", "aspect": "3:4"}'

La risposta è 202 Accepted con il disegno in coda e un header Location. Interroga GET /v1/pages/{id} ogni 2 secondi finché status non diventa succeeded (a quel punto imageUrl è un link valido 15 minuti al file PNG) o failed (il credito viene rimborsato). Un disegno richiede circa 5 secondi. La stessa richiesta entro 2 minuti restituisce lo stesso disegno senza addebitare di nuovo.

Endpoint

Metodo e percorso	Cosa fa	Costo
`POST /v1/pages`	Un disegno da una descrizione (`subject`, `level`, `aspect`, `frame`, `characterId`, `count` 1–4)	1 credito per disegno
`POST /v1/pages/photo`	Un disegno tracciato da una foto caricata con `/v1/files`	1 credito
`POST /v1/ideas`	Idee per disegni su un tema	Gratis (limite giornaliero)
`POST /v1/pages/batch`	Un disegno per idea (Creator 10, Pro 50 per richiesta)	1 credito per disegno
`GET /v1/pages`, `GET /v1/pages/{id}`	La libreria; un singolo disegno	Gratis
`POST /v1/pages/{id}/edit`, `/again`	Una modifica testuale; un'altra versione	1 credito
`GET /v1/pages/{id}/download`, `/versions`; `DELETE /v1/pages/{id}`	Link per il download; versioni; elimina	Gratis
`GET/POST /v1/characters`	Elenco; salva un personaggio da un disegno	Gratis
`GET /v1/books`, `GET /v1/books/{id}`	Libri e link firmati alle loro pagine	Gratis
`POST /v1/files/upload-url`, `/confirm`	Carica una foto direttamente nello storage	Gratis

Livelli: kids, medium, detailed. Proporzioni: 3:4 (Letter, A4), 4:5 (8×10), 2:3 (6×9), 1:1, 4:3. Metti le parole tra virgolette nel soggetto per farle apparire scritte sul disegno.

Limiti ed errori

1.200 richieste all'ora per chiave, polling incluso; ogni risposta include gli header RateLimit-Policy e RateLimit, e un errore 429 ha Retry-After. Gli errori sono in JSON: {"error": "no_credits", "message": "..."}. Codici comuni: no_credits (402), plan_required (403), content_refused (422), capacity (503).

I file PDF e SVG vengono generati sul dispositivo nell'app; tramite API ricevi il PNG (circa 1 megapixel).