Skip to main content
Mit der Agent API gibst du Krea Agent eine Aufgabe aus deiner eigenen Anwendung. Anfragen und Antworten verwenden JSON-Felder in camelCase. Der Agent arbeitet im Hintergrund, während deine Anwendung seinen Fortschritt und seine Ergebnisse ausliest.
Der Agent arbeitet im Hintergrund. Er stellt keine Rückfragen, und Kosten- und Berechtigungsabfragen werden automatisch genehmigt. Nimm alle Anforderungen und Einschränkungen in deinen Prompt auf. Prüfe die Aufgabe, bevor du sie absendest.

Authentifizierung, Zugriff und Abrechnung

Sende bei jeder Anfrage an https://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.
Jede Antwort enthält eine 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 zuerst KREA_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.
Installiere für Python 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

Verwende GET /agent/session/{sessionId}, um einen Snapshot der aktuellen Session abzurufen:
cURL

Die Session fortsetzen

Wenn der Zug abgeschlossen ist, sende eine weitere Nachricht mit seiner sessionId:
cURL
Eine Session führt jeweils nur einen Zug aus. Wenn du eine weitere Nachricht sendest, während ein Zug läuft, wird 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.