Authentifizierung, Zugriff und Abrechnung
Sende bei jeder Anfrage anhttps://api.krea.ai den Header Authorization: Bearer KREA_API_KEY. Persönliche, Service- und Legacy-API-Schlüssel verwenden die standardmäßige Authentifizierung der öffentlichen API.
Du kannst nur Sessions lesen oder fortsetzen, die dem authentifizierten Aufrufer im authentifizierten Workspace gehören. Die Kenntnis einer Session-ID gewährt keinen Zugriff. Angehängte Krea-Dateien müssen für diesen Aufrufer in diesem Workspace ebenfalls zugänglich sein.
Agent-Züge verbrauchen das Compute-Unit-Guthaben des Workspaces. Sie verbrauchen nicht das API-Guthaben. Die Berechtigungen des Agent-Plans und die Nachrichtenlimits des Free-Plans gelten weiterhin. Siehe Agent: Pläne, Zugang und Credits.
url, unter der du die Session in der Krea-App mit dem passenden Konto- und Workspace-Zugriff öffnen kannst.
Eine Session starten und auf ihr Ergebnis warten
Setze zuerstKREA_API_KEY in deiner Umgebung. Wähle Bash mit curl und jq, Python mit requests oder Node.js mit dem integrierten fetch oder dem Krea SDK.
1
Den ersten Zug senden
Lass
sessionId weg, um eine Session zu erstellen. Speichere die zurückgegebenen Werte sessionId und runId. Die Antwort kommt sofort mit status: "running" zurück.2
Auf diesen Zug warten
Übergib beide IDs an
wait-for-session. Wenn timedOut true ist, rufe den Endpoint erneut mit denselben IDs auf. Ein Timeout bricht den Zug nicht ab.3
Das Ergebnis lesen
Prüfe
status, wenn finished true ist. Sieh dir text, media und einen eventuellen error an oder öffne die zurückgegebene url.requests mit pip install requests. Verwende für Node.js Node.js 22+ und speichere das Beispiel als example.mjs. Das SDK-Beispiel erfordert npm install @krea-ai/sdk und verwendet requestRaw, um die HTTP-Endpoints aufzurufen.
Diese Beispiele senden eine Nachricht und warten bis zu fünf Minuten. Sie brechen bei HTTP-Fehlern sowie bei fehlgeschlagenen oder abgebrochenen Zügen ab. Sie wiederholen einen Sendevorgang nie automatisch. Wenn bei einer Sendeanfrage ein Timeout auftritt, prüfe die Session in Krea, bevor du erneut sendest; die erste Anfrage hat möglicherweise bereits einen Zug gestartet.
Wenn das Warte-Budget abläuft, läuft der Zug im Hintergrund weiter. Speichere die ausgegebenen Session- und Run-IDs, um später weiter zu warten.
timeoutSeconds ist eine Ganzzahl von 1 bis 300 und hat den Standardwert 60. Halte das Timeout deines HTTP-Clients länger als die angeforderte Wartezeit. Übergib beim Warten nach einem Sendevorgang immer die neueste runId, damit der Endstatus eines vorherigen Zugs nicht mit dem des neuen Zugs verwechselt wird.
Ohne Warten lesen
VerwendeGET /agent/session/{sessionId}, um einen Snapshot der aktuellen Session abzurufen:
cURL
Die Session fortsetzen
Wenn der Zug abgeschlossen ist, sende eine weitere Nachricht mit seinersessionId:
cURL
409 mit code: "conflict" zurückgegeben.
Eingaben und Anhänge
send-message akzeptiert diese Felder. Das vollständige Modell-Enum und die Schemas findest du in der Referenz.
Die
url eines Anhangs akzeptiert eine zugängliche HTTP(S)-URL oder eine autorisierte Krea-Files-URI wie file:550e8400-e29b-41d4-a716-446655440000. Die optionalen Felder name und contentType sind getrimmte, nicht leere Strings mit bis zu 255 Zeichen. Lokale Pfade des Aufrufers und OpenAI-file_-IDs werden nicht unterstützt. Übertrage zuerst die eigentliche Datei; eine ID im Prompt-Text überträgt nicht deren Inhalt.
Der Agent übernimmt weder die Konversation noch die Anhänge deiner Anwendung. Hänge Referenzdateien an, die nicht anderweitig zugänglich sind. Nutzbare URLs im Prompt, vorhandener Krea-Kontext oder frühere Session-Dateien müssen nicht wiederholt werden.
Session-Ergebnisse
send-message gibt sessionId, threadId, runId, status (immer "running") und url zurück.
GET /agent/session/{sessionId} und wait-for-session geben die folgende Session-Ansicht zurück. Nur wait-for-session ergänzt das Pflichtfeld timedOut.
Jedes
media-Element kann eine Generierung (jobId und optional mediaKind: image, video, audio oder 3d), neu gehostete Medien (url, optional mit mimeType) oder eine Krea-Datei (uri, name, mimeType) darstellen. Details zu einer Generierung rufst du über GET /jobs/{jobId} ab. Du kannst die URI einer Krea-Datei als Anhang wiederverwenden oder die url der Session öffnen, um ihre Dateien anzusehen. Medien können bereits erscheinen, während der Zug noch läuft.
Fehler
Endpoint-Fehler verwenden{ "error": "...", "code": "...", "allowedModels": ["..."] }. Nur error ist erforderlich. Ein Zug, der nach dem Senden fehlschlägt, erscheint stattdessen als status: "failed" in einer erfolgreichen Session-Antwort.