Skip to main content
Utilisez l’Agent API pour confier une tâche à Krea Agent depuis votre propre application. Les requêtes et les réponses utilisent des champs JSON en camelCase. L’agent travaille en arrière-plan pendant que votre application lit sa progression et ses résultats.
L’agent travaille en arrière-plan. Il ne pose pas de questions, et les demandes de confirmation de coût et d’autorisation sont approuvées automatiquement. Incluez toutes les exigences et contraintes dans votre prompt. Relisez la tâche avant de la soumettre.

Authentification, accès et facturation

Envoyez Authorization: Bearer KREA_API_KEY avec chaque requête vers https://api.krea.ai. Les clés API personnelles, de service et legacy utilisent l’authentification standard de l’API publique. Vous ne pouvez lire ou poursuivre que les sessions appartenant à l’appelant authentifié dans l’espace de travail authentifié. Connaître l’ID d’une session ne donne pas accès à celle-ci. Les fichiers Krea joints doivent également être accessibles à cet appelant dans cet espace de travail.
Les tours de l’agent utilisent le solde d’unités de calcul de l’espace de travail. Ils n’utilisent pas le solde API. Les droits du plan Agent et les limites de messages du plan Free s’appliquent toujours. Consultez Plans, accès et crédits de l’agent.
Chaque réponse inclut une url permettant d’ouvrir la session dans l’application Krea avec le compte et l’accès à l’espace de travail appropriés.

Démarrer une session et attendre son résultat

Définissez d’abord KREA_API_KEY dans votre environnement. Choisissez Bash avec curl et jq, Python avec requests, ou Node.js avec fetch intégré ou le SDK Krea.
1

Soumettre le premier tour

Omettez sessionId pour créer une session. Enregistrez le sessionId et le runId renvoyés. La réponse est renvoyée immédiatement avec status: "running".
2

Attendre ce tour

Transmettez les deux ID à wait-for-session. Si timedOut vaut true, rappelez l’endpoint avec les mêmes ID. Un dépassement de délai n’annule pas le tour.
3

Lire le résultat

Vérifiez status lorsque finished vaut true. Examinez text, media et l’éventuelle error, ou ouvrez l’url renvoyée.
Pour Python, installez requests avec pip install requests. Pour Node.js, utilisez Node.js 22+ et enregistrez l’exemple sous example.mjs. L’exemple SDK nécessite npm install @krea-ai/sdk et utilise requestRaw pour appeler les endpoints HTTP. Ces exemples soumettent un message et attendent jusqu’à cinq minutes. Ils s’arrêtent en cas d’erreur HTTP et de tour échoué ou annulé. Ils ne relancent jamais automatiquement un envoi. Si une requête d’envoi dépasse le délai, vérifiez la session dans Krea avant de soumettre à nouveau ; la première requête a peut-être déjà démarré un tour. Lorsque le budget d’attente expire, le tour continue en arrière-plan. Enregistrez les ID de session et d’exécution affichés pour reprendre l’attente plus tard. timeoutSeconds est un entier de 1 à 300, avec 60 par défaut. Gardez le délai de votre client HTTP plus long que l’attente demandée. Transmettez toujours le dernier runId lorsque vous attendez après un envoi, afin que le statut final d’un tour précédent ne soit pas confondu avec celui du nouveau tour.

Lire sans attendre

Utilisez GET /agent/session/{sessionId} pour obtenir un instantané de la session actuelle :
cURL

Poursuivre la session

Une fois le tour terminé, envoyez un autre message avec son sessionId :
cURL
Une session exécute un tour à la fois. Envoyer un autre message pendant qu’un tour est en cours renvoie 409 avec code: "conflict".

Entrées et pièces jointes

send-message accepte ces champs. Consultez la référence pour l’enum complet des modèles et les schémas. L’url d’une pièce jointe accepte une URL HTTP(S) accessible ou un URI Krea Files autorisé tel que file:550e8400-e29b-41d4-a716-446655440000. Les champs facultatifs name et contentType sont des chaînes non vides, sans espaces aux extrémités, de 255 caractères maximum. Les chemins locaux de l’appelant et les ID OpenAI file_ ne sont pas pris en charge. Transférez d’abord le fichier lui-même ; un ID dans le texte du prompt ne transfère pas son contenu. L’agent n’hérite pas de la conversation ni des pièces jointes de votre application. Joignez les fichiers de référence qui ne sont pas accessibles autrement. Inutile de répéter les URL utilisables dans le prompt, le contexte Krea existant ou les fichiers de session précédents.

Résultats de session

send-message renvoie sessionId, threadId, runId, status (toujours "running") et url. GET /agent/session/{sessionId} et wait-for-session renvoient la vue de session suivante. Seul wait-for-session ajoute le champ obligatoire timedOut. Chaque élément de media peut représenter une génération (jobId et mediaKind facultatif : image, video, audio ou 3d), un média réhébergé (url, avec mimeType facultatif) ou un fichier Krea (uri, name, mimeType). Récupérez les détails d’une génération via GET /jobs/{jobId}. Vous pouvez réutiliser l’URI d’un fichier Krea comme pièce jointe ou ouvrir l’url de la session pour voir ses fichiers. Des médias peuvent apparaître alors que le tour est encore en cours.

Erreurs

Les erreurs des endpoints utilisent { "error": "...", "code": "...", "allowedModels": ["..."] }. Seul error est obligatoire. Un tour qui échoue après sa soumission apparaît plutôt sous la forme status: "failed" dans une réponse de session réussie.