Autenticazione, accesso e fatturazione
InviaAuthorization: Bearer KREA_API_KEY con ogni richiesta a https://api.krea.ai. Le chiavi API personali, di servizio e legacy usano l’autenticazione standard dell’API pubblica.
Puoi leggere o continuare solo le sessioni di proprietà dell’utente autenticato nel workspace autenticato. Conoscere l’ID di una sessione non dà accesso. Anche i file Krea allegati devono essere accessibili a quell’utente in quel workspace.
I turni dell’agente usano il saldo di unità di calcolo del workspace. Non usano il saldo API. Restano validi i diritti del piano Agent e i limiti di messaggi del piano Free. Vedi Piani, accesso e crediti di Agent.
url con cui puoi aprire la sessione nell’app Krea, se disponi dell’accesso appropriato all’account e al workspace.
Avviare una sessione e attenderne il risultato
Per prima cosa, impostaKREA_API_KEY nel tuo ambiente. Scegli Bash con curl e jq, Python con requests oppure Node.js con fetch integrato o l’SDK di Krea.
1
Invia il primo turno
Ometti
sessionId per creare una sessione. Salva il sessionId e il runId restituiti. La risposta arriva subito con status: "running".2
Attendi la fine di questo turno
Passa entrambi gli ID a
wait-for-session. Se timedOut è true, richiamalo con gli stessi ID. Un timeout non annulla il turno.3
Leggi il risultato
Controlla
status quando finished è true. Esamina text, media ed eventuali error, oppure apri l’url restituito.requests con pip install requests. Per Node.js, usa Node.js 22+ e salva l’esempio come example.mjs. L’esempio con l’SDK richiede npm install @krea-ai/sdk e usa requestRaw per chiamare gli endpoint HTTP.
Questi esempi inviano un messaggio e attendono fino a cinque minuti. Si fermano in caso di errori HTTP e di turni falliti o annullati. Non ritentano mai un invio automaticamente. Se una richiesta di invio va in timeout, controlla la sessione in Krea prima di inviarla di nuovo: la prima richiesta potrebbe aver già avviato un turno.
Quando il tempo di attesa scade, il turno continua in background. Salva gli ID di sessione e di esecuzione stampati per riprendere l’attesa in seguito.
timeoutSeconds è un intero da 1 a 300 e il valore predefinito è 60. Mantieni il timeout del tuo client HTTP più lungo dell’attesa richiesta. Passa sempre il runId più recente quando attendi dopo un invio, così lo stato terminale di un turno precedente non viene scambiato per quello del nuovo turno.
Leggere senza attendere
UsaGET /agent/session/{sessionId} per ottenere un’istantanea della sessione corrente:
cURL
Continuare la sessione
Al termine del turno, invia un altro messaggio con il relativosessionId:
cURL
409 con code: "conflict".
Input e allegati
send-message accetta questi campi. Consulta il riferimento per l’enum completo dei modelli e gli schemi.
L’
url di un allegato accetta un URL HTTP(S) accessibile o un URI autorizzato di Krea Files, come file:550e8400-e29b-41d4-a716-446655440000. I campi facoltativi name e contentType sono stringhe non vuote, senza spazi iniziali e finali, di massimo 255 caratteri. I percorsi locali dell’utente e gli ID file_ di OpenAI non sono supportati. Trasferisci prima il file vero e proprio: un ID nel testo del prompt non ne trasferisce il contenuto.
L’agente non eredita la conversazione né gli allegati della tua applicazione. Allega i file di riferimento che non sono accessibili in altro modo. Non è necessario ripetere gli URL utilizzabili già presenti nel prompt, nel contesto Krea esistente o nei file precedenti della sessione.
Risultati della sessione
send-message restituisce sessionId, threadId, runId, status (sempre "running") e url.
GET /agent/session/{sessionId} e wait-for-session restituiscono la seguente vista della sessione. Solo wait-for-session aggiunge il campo obbligatorio timedOut.
Ogni elemento di
media può rappresentare una generazione (jobId e mediaKind facoltativo: image, video, audio o 3d), un contenuto multimediale ri-ospitato (url, con mimeType facoltativo) o un file Krea (uri, name, mimeType). Recupera i dettagli della generazione tramite GET /jobs/{jobId}. Puoi riutilizzare l’URI di un file Krea come allegato oppure aprire l’url della sessione per vederne i file. I contenuti multimediali possono comparire mentre il turno è ancora in corso.
Errori
Gli errori degli endpoint usano{ "error": "...", "code": "...", "allowedModels": ["..."] }. Solo error è obbligatorio. Un turno che fallisce dopo l’invio compare invece come status: "failed" in una risposta di sessione riuscita.