> ## Documentation Index
> Fetch the complete documentation index at: https://www.krea.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent API

> Gérez des sessions Krea Agent via HTTP : démarrez une session, attendez la fin d'un tour, lisez ses résultats et envoyez des relances avec votre clé API.

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.

| Endpoint | Rôle |
| - | - |
| [`POST /agent/send-message`](/docs/api-reference/agent/send-agent-message) | Démarrer une session ou soumettre un tour de relance. |
| [`GET /agent/session/{sessionId}`](/docs/api-reference/agent/get-agent-session) | Lire la session actuelle sans attendre. |
| [`POST /agent/wait-for-session`](/docs/api-reference/agent/wait-for-agent-session) | Attendre la fin d'un tour, dans la limite d'un délai. |

<Warning>
  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.
</Warning>

## 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](/docs/fr/developers/api-keys-and-billing).

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.

<Info>
  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](/docs/fr/user-guide/agent/plans-and-credits).
</Info>

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.

<Steps>
  <Step title="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"`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Lire le résultat">
    Vérifiez `status` lorsque `finished` vaut `true`. Examinez `text`, `media` et l'éventuelle `error`, ou ouvrez l'`url` renvoyée.
  </Step>
</Steps>

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  set -euo pipefail
  : "${KREA_API_KEY:?Set your Krea API key}"

  START=$(curl --fail-with-body --silent --show-error --max-time 60 \
    https://api.krea.ai/agent/send-message \
    -H "Authorization: Bearer $KREA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
      "name": "Coffee mug campaign"
    }')

  SESSION_ID=$(printf '%s' "$START" | jq -er '.sessionId')
  RUN_ID=$(printf '%s' "$START" | jq -er '.runId')
  printf '%s' "$START" | jq -r '.url'

  DEADLINE=$((SECONDS + 300))

  while (( SECONDS < DEADLINE - 10 )); do
    WAIT_SECONDS=$((DEADLINE - SECONDS - 10))
    if (( WAIT_SECONDS > 60 )); then WAIT_SECONDS=60; fi
    WAIT_BODY=$(jq -n --arg sessionId "$SESSION_ID" --arg runId "$RUN_ID" \
      --argjson timeoutSeconds "$WAIT_SECONDS" \
      '{sessionId: $sessionId, runId: $runId, timeoutSeconds: $timeoutSeconds}')
    RESULT=$(curl --fail-with-body --silent --show-error --max-time "$((WAIT_SECONDS + 10))" \
      https://api.krea.ai/agent/wait-for-session \
      -H "Authorization: Bearer $KREA_API_KEY" \
      -H "Content-Type: application/json" \
      -d "$WAIT_BODY")
    printf '%s' "$RESULT" | jq '{status, finished, timedOut, text, media, error, url}'
    if printf '%s' "$RESULT" | jq -e '.finished' > /dev/null; then
      if printf '%s' "$RESULT" | jq -e '.status == "completed"' > /dev/null; then
        exit 0
      fi
      printf '%s' "$RESULT" | jq -r '"Turn ended: \(.status). \(.error // "No error details")"' >&2
      exit 1
    fi
  done

  printf 'Wait budget exhausted; the turn continues. Resume waiting with sessionId=%s runId=%s\n' \
    "$SESSION_ID" "$RUN_ID" >&2
  exit 1
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  import json
  import os
  import time
  import requests

  api = "https://api.krea.ai"
  headers = {"Authorization": f"Bearer {os.environ['KREA_API_KEY']}"}

  response = requests.post(
      f"{api}/agent/send-message",
      headers=headers,
      json={
          "prompt": "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
          "name": "Coffee mug campaign",
      },
      timeout=60,
  )
  response.raise_for_status()
  start = response.json()
  session_id, run_id = start["sessionId"], start["runId"]
  print(start["url"])

  deadline = time.monotonic() + 300
  while True:
      wait_seconds = min(60, int(deadline - time.monotonic()) - 10)
      if wait_seconds < 1:
          raise TimeoutError(
              "Wait budget exhausted; the turn continues. Resume waiting with "
              f"sessionId={session_id} runId={run_id}"
          )
      response = requests.post(
          f"{api}/agent/wait-for-session",
          headers=headers,
          json={
              "sessionId": session_id,
              "runId": run_id,
              "timeoutSeconds": wait_seconds,
          },
          timeout=wait_seconds + 10,
      )
      response.raise_for_status()
      result = response.json()
      print(json.dumps(result, indent=2))
      if result["finished"]:
          if result["status"] != "completed":
              raise RuntimeError(
                  f"Turn ended: {result['status']}. {result.get('error', 'No error details')}"
              )
          break
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  import { performance } from "node:perf_hooks";

  const token = process.env.KREA_API_KEY;
  if (!token) throw new Error("Set your Krea API key");
  const api = "https://api.krea.ai";

  async function post(path, body, timeoutMs) {
    const response = await fetch(`${api}${path}`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(timeoutMs),
    });
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    }
    return response.json();
  }

  const start = await post("/agent/send-message", {
    prompt: "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
    name: "Coffee mug campaign",
  }, 60_000);
  const { sessionId, runId } = start;
  console.log(start.url);

  const deadline = performance.now() + 300_000;
  while (true) {
    const timeoutSeconds = Math.min(60, Math.floor((deadline - performance.now()) / 1000) - 10);
    if (timeoutSeconds < 1) {
      throw new Error(
        `Wait budget exhausted; the turn continues. Resume waiting with sessionId=${sessionId} runId=${runId}`,
      );
    }
    const result = await post("/agent/wait-for-session", {
      sessionId,
      runId,
      timeoutSeconds,
    }, (timeoutSeconds + 10) * 1000);
    console.log(JSON.stringify(result, null, 2));
    if (result.finished) {
      if (result.status !== "completed") {
        throw new Error(`Turn ended: ${result.status}. ${result.error ?? "No error details"}`);
      }
      break;
    }
  }
  ```

  ```javascript Node.js (SDK) theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  import { performance } from "node:perf_hooks";
  import { Krea } from "@krea-ai/sdk";

  const token = process.env.KREA_API_KEY;
  if (!token) throw new Error("Set your Krea API key");
  const krea = new Krea({ apiKey: token });

  const start = await krea.requestRaw("/agent/send-message", {
    method: "POST",
    retry: false,
    signal: AbortSignal.timeout(60_000),
    body: {
      prompt: "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
      name: "Coffee mug campaign",
    },
  });
  const { sessionId, runId } = start;
  console.log(start.url);

  const deadline = performance.now() + 300_000;
  while (true) {
    const timeoutSeconds = Math.min(60, Math.floor((deadline - performance.now()) / 1000) - 15);
    if (timeoutSeconds < 1) {
      throw new Error(
        `Wait budget exhausted; the turn continues. Resume waiting with sessionId=${sessionId} runId=${runId}`,
      );
    }
    const result = await krea.requestRaw("/agent/wait-for-session", {
      method: "POST",
      retry: false,
      signal: AbortSignal.timeout((timeoutSeconds + 15) * 1000),
      body: { sessionId, runId, timeoutSeconds },
    });
    console.log(JSON.stringify(result, null, 2));
    if (result.finished) {
      if (result.status !== "completed") {
        throw new Error(`Turn ended: ${result.status}. ${result.error ?? "No error details"}`);
      }
      break;
    }
  }
  ```
</CodeGroup>

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 :

```bash cURL theme={"theme":{"light":"github-light-default","dark":"vesper"}}
curl --fail-with-body --silent --show-error \
  "https://api.krea.ai/agent/session/$SESSION_ID" \
  -H "Authorization: Bearer $KREA_API_KEY"
```

### Poursuivre la session

Une fois le tour terminé, envoyez un autre message avec son `sessionId` :

```bash cURL theme={"theme":{"light":"github-light-default","dark":"vesper"}}
FOLLOW_UP=$(curl --fail-with-body --silent --show-error \
  https://api.krea.ai/agent/send-message \
  -H "Authorization: Bearer $KREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg sessionId "$SESSION_ID" \
    '{sessionId: $sessionId, prompt: "Make a landscape variation of the first image."}')")

# Use this new runId in the next wait-for-session request.
RUN_ID=$(printf '%s' "$FOLLOW_UP" | jq -er '.runId')
```

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](/docs/api-reference/agent/send-agent-message) pour l'enum complet des modèles et les schémas.

| Champ | Comportement |
| - | - |
| `sessionId` | UUID facultatif. Omettez-le pour une nouvelle session ; incluez-le pour poursuivre une session vous appartenant. |
| `prompt` | Chaîne de 100 000 caractères maximum. Valeur par défaut : `""`. Un prompt non vide ou au moins une pièce jointe est requis. |
| `attachments` | Jusqu'à 20 pièces jointes. Valeur par défaut : `[]`. Chacune nécessite une `url` et peut inclure `name` et `contentType`. |
| `model` | ID facultatif du LLM de l'agent. Omettez-le pour Auto. Un modèle épinglé doit être inclus dans le plan de l'espace de travail. |
| `effort` | Facultatif : `fast`, `default`, `high` ou `xhigh`. Les nouvelles sessions utilisent `default` par défaut ; omettez-le pour conserver l'effort d'une session existante. |
| `name` | Nom de session facultatif, pour les nouvelles sessions uniquement. Espaces supprimés aux extrémités, non vide et de 120 caractères maximum. |
| `desktopAppId` | UUID facultatif identifiant une application de bureau connectée. Exécute ce tour dans cette application. L'application doit être disponible pour l'appelant et l'espace de travail authentifiés. |

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`.

| Champ | Signification |
| - | - |
| `sessionId`, `threadId` | Identifiants de la session et du thread racine. |
| `runId` | Identifiant du tour actuel, lorsqu'il est disponible. |
| `status` | `not_started`, `running`, `completed`, `failed` ou `cancelled`. |
| `finished` | `true` pour un tour terminé. Si un `runId` est fourni à une attente, le tour terminé doit aussi correspondre à cet ID. |
| `text` | Texte du dernier message de l'assistant. |
| `media` | Tableau des médias produits par la session. L'ordre n'est pas significatif. |
| `error` | Texte d'erreur facultatif pour la session. |
| `url` | Lien vers la session dans l'application Krea. |
| `timedOut` | Réponses d'attente uniquement : `true` si le délai a expiré avant la fin du tour demandé. |

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.

| Statut HTTP | Signification |
| - | - |
| `400` | Corps JSON mal formé. |
| `401` | Authentification manquante ou invalide. |
| `402` | Solde d'unités de calcul insuffisant dans l'espace de travail (`compute_limit`) ou limite de messages du plan Free atteinte (`free_message_limit`). |
| `403` | Le modèle épinglé n'est pas inclus dans les droits (`model_not_entitled`) ; `allowedModels` liste les ID autorisés. |
| `404` | Session introuvable ou inaccessible (`not_found`), ou fichier Krea joint introuvable ou inaccessible (`attachment_not_found`). |
| `409` | Un tour est déjà en cours (`conflict`). |
| `422` | Entrée invalide, ou l'application de bureau sélectionnée n'est pas disponible. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.