Skip to main content
Usa la Agent API per assegnare un compito a Krea Agent dalla tua applicazione. Richieste e risposte usano campi JSON in camelCase. L’agente lavora in background mentre la tua applicazione ne legge l’avanzamento e i risultati.
L’agente lavora in background. Non fa domande, e le richieste di conferma su costi e permessi vengono approvate automaticamente. Includi tutti i requisiti e i vincoli nel tuo prompt. Rivedi il compito prima di inviarlo.

Autenticazione, accesso e fatturazione

Invia Authorization: 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.
Ogni risposta include un 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, imposta KREA_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.
Per Python, installa 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

Usa GET /agent/session/{sessionId} per ottenere un’istantanea della sessione corrente:
cURL

Continuare la sessione

Al termine del turno, invia un altro messaggio con il relativo sessionId:
cURL
Una sessione esegue un turno alla volta. Inviare un altro messaggio mentre un turno è in corso restituisce 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.