Authentification, accès et facturation
EnvoyezAuthorization: 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.
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’abordKREA_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.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
UtilisezGET /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 sonsessionId :
cURL
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.