Authentication, access, and billing
SendAuthorization: Bearer KREA_API_KEY with every request to https://api.krea.ai. Personal, service, and legacy API keys use the standard public API authentication.
You can only read or continue sessions owned by the authenticated caller in the authenticated workspace. Knowing a session ID does not grant access. Krea file attachments must also be accessible to that caller in that workspace.
Agent turns use the workspace’s compute unit balance. They do not use the API balance. Agent plan entitlements and Free plan message limits still apply. See Agent plans, access, and credits.
url where you can open the session in the Krea app with the appropriate account and workspace access.
Start a session and wait for its result
SetKREA_API_KEY in your environment first. Choose Bash with curl and jq, Python with requests, or Node.js with built-in fetch or the Krea SDK.
1
Submit the first turn
Omit
sessionId to create a session. Save the returned sessionId and runId. The response returns immediately with status: "running".2
Wait for this turn
Pass both IDs to
wait-for-session. If timedOut is true, call it again with the same IDs. A timeout does not cancel the turn.3
Read the result
Check
status when finished is true. Inspect text, media, and any error, or open the returned url.requests with pip install requests. For Node.js, use Node.js 22+ and save the example as example.mjs. The SDK example requires npm install @krea-ai/sdk and uses requestRaw to call the HTTP endpoints.
These examples submit one message and wait for up to five minutes. They stop on HTTP errors and failed or cancelled turns. They never retry a send automatically. If a send request times out, check the session in Krea before submitting again; the first request may have started a turn.
When the wait budget expires, the turn continues in the background. Save the printed session and run IDs to resume waiting later.
timeoutSeconds is an integer from 1 to 300 and defaults to 60. Keep your HTTP client timeout longer than the requested wait. Always pass the latest runId when waiting after a send, so a previous turn’s terminal status is not mistaken for the new turn.
Read without waiting
UseGET /agent/session/{sessionId} to take a snapshot of the current session:
cURL
Continue the session
After the turn finishes, send another message with itssessionId:
cURL
409 with code: "conflict".
Inputs and attachments
send-message accepts these fields. See the reference for the full model enum and schemas.
Attachment
url accepts an accessible HTTP(S) URL or an authorized Krea Files URI such as file:550e8400-e29b-41d4-a716-446655440000. Optional name and contentType are trimmed, nonempty strings of up to 255 characters. Caller-local paths and OpenAI file_ IDs are not supported. Transfer the actual file first; an ID in prompt text does not transfer its contents.
The Agent does not inherit your application’s conversation or attachments. Attach reference files that are not otherwise accessible. You do not need to repeat usable URLs in the prompt, existing Krea context, or prior session files.
Session results
send-message returns sessionId, threadId, runId, status (always "running"), and url.
GET /agent/session/{sessionId} and wait-for-session return the following session view. Only wait-for-session adds the required timedOut field.
Each
media item can represent a generation (jobId and optional mediaKind: image, video, audio, or 3d), rehosted media (url, with optional mimeType), or a Krea file (uri, name, mimeType). Fetch generation details through GET /jobs/{jobId}. You can reuse a Krea file URI as an attachment or open the session’s url to view its files. Media can appear while the turn is still running.
Errors
Endpoint errors use{ "error": "...", "code": "...", "allowedModels": ["..."] }. Only error is required. A turn that fails after submission appears as status: "failed" in a successful session response instead.