Sur cette page

Référence de l'API

Intégrez votre agent.

Votre agent utilise le format de chat compatible OpenAI. Les SDK officiels et la plupart des outils d'IA fonctionnent avec lui tels quels. Indiquez notre URL de base, envoyez votre clé API et renseignez l'identifiant de votre agent comme modèle.

URL de base https://atelieragents.com/v1

Modèle your-agent-id

En-tête de la clé Authorization: Bearer YOUR_API_KEY

Les exemples utilisent your-agent-id et YOUR_API_KEY comme valeurs à remplacer. Ouvrez votre espace client et cette page affichera l'identifiant de votre agent.

Présentation

Un agent est un modèle d'IA que nous configurons pour l'une de vos tâches. Ses instructions, son ton et ses limites sont intégrés. Vous lui envoyez la matière à traiter (un e-mail, une facture, un prospect) et il vous renvoie le résultat.

URL de base. https://atelieragents.com/v1
Modèle. L'identifiant de votre agent, par exemple invoice-clerk. Chaque clé appartient à un seul agent, et les réponses le nomment toujours dans model.
Format. Du JSON sur HTTP, au format chat completions d'OpenAI.
Facturation. Au token, lu et écrit. Voir Tokens et facturation.
Langue de l'API. Les messages d'erreur et les noms de champs sont en anglais, quelle que soit la langue de votre espace client.

Endpoints
Endpoint	Rôle
POST `/v1/chat/completions`	Chat compatible OpenAI, avec streaming en option. Détails
POST `/v1/run`	Envoyez un texte, recevez un texte. Pensé pour les outils no-code et les scripts courts. Détails
GET `/v1/models`	L'agent que votre clé peut appeler. Détails
GET `/v1/models/{id}`	La fiche d'un modèle.
GET `/v1/usage`	Solde, formule, tokens inclus et consommation du mois en cours. Détails

Démarrage rapide

Retrouvez votre clé. Elle figure dans l'e-mail envoyé à la mise en service de votre agent et commence par ak_.
Collez-la à la place de YOUR_API_KEY ci-dessous.
Lancez l'appel. C'est tout.

curl https://atelieragents.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-agent-id",
    "messages": [
      {"role": "user", "content": "Collez ici le texte à traiter par votre agent."}
    ]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://atelieragents.com/v1",
    api_key="YOUR_API_KEY",
)

reply = client.chat.completions.create(
    model="your-agent-id",
    messages=[{"role": "user", "content": "Collez ici le texte à traiter par votre agent."}],
)
print(reply.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://atelieragents.com/v1",
  apiKey: "YOUR_API_KEY",
});

const reply = await client.chat.completions.create({
  model: "your-agent-id",
  messages: [{ role: "user", content: "Collez ici le texte à traiter par votre agent." }],
});
console.log(reply.choices[0].message.content);

La réponse se trouve dans choices[0].message.content. Le nombre de tokens est dans usage, et le coût de l'appel dans l'en-tête de réponse X-Cost.

Authentification

Envoyez votre clé à chaque requête, dans l'un de ces deux en-têtes.

En-têtes (un seul suffit)

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY

Les clés commencent par ak_. Votre espace client n'en affiche que les premiers caractères ; la clé complète figure dans l'e-mail que nous vous avons envoyé.
Gardez vos clés côté serveur, dans une variable d'environnement, un gestionnaire de secrets ou les identifiants de votre outil. L'API accepte les appels depuis un navigateur (CORS), mais une clé placée dans une page web ou une application mobile peut être lue par n'importe qui, et utilisée à vos frais.
Utilisez une clé par intégration pour distinguer facilement les consommations. Demandez-nous des clés supplémentaires.
Nous ne pouvons pas vous renvoyer une clé. Si vous en perdez une, écrivez-nous, nous la révoquons et vous en créons une nouvelle. Si une clé a été exposée, prévenez-nous. Nous réinitialisons aussi le lien privé vers votre espace client, ce qui ferme toutes les sessions ouvertes, et nous vous envoyons le nouveau lien.
Une clé absente, mal saisie ou révoquée reçoit une erreur 401 avec le code invalid_api_key.

Chat completions

POST https://atelieragents.com/v1/chat/completions

La requête et la réponse suivent le format chat completions d'OpenAI. Votre code existant continue de fonctionner avec une nouvelle URL de base. Le champ model que vous envoyez est accepté puis ignoré, car c'est votre clé qui détermine l'agent qui répond, et la réponse le nomme.

Corps de la requête

{
  "model": "your-agent-id",
  "messages": [
    {
      "role": "system",
      "content": "Répondez en anglais."
    },
    {
      "role": "user",
      "content": "Texte de la facture à traiter."
    }
  ],
  "max_tokens": 400,
  "temperature": 0.2
}

Réponse

{
  "id": "chatcmpl-7c1e",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "your-agent-id",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Total à payer : 1 250,00"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 412,
    "completion_tokens": 38,
    "total_tokens": 450
  }
}

X-Tokens-Used 450X-Cost 0.0054X-Balance 42.0946X-Included-Remaining 0

Paramètres

Paramètres de la requête
Paramètre	Type	Remarques
`messages` obligatoire	tableau	Rôles `system`, `developer`, `user`, `assistant`, `tool`. Le contenu est une chaîne ou un tableau de parties de contenu. Au moins un message qui n'est pas un message système.
`model`	chaîne	Facultatif et ignoré. Les réponses renvoient l'identifiant de votre agent.
`max_tokens`, `max_completion_tokens`	entier, 1 ou plus	Longueur maximale de la réponse, en tokens. Plafonnée au maximum de votre agent, qui est aussi la valeur par défaut.
`temperature`	nombre, de 0 à 2	Par défaut, le réglage de votre agent.
`top_p`	nombre, de 0 à 1	Par défaut, le réglage de votre agent.
`stream`, `stream_options`	booléen, objet	Voir Streaming.
`stop`	chaîne ou tableau	Séquences qui arrêtent la réponse.
`seed`	entier	Transmis tel quel.
`presence_penalty`, `frequency_penalty`	nombre, de -2 à 2	Transmis tels quels.
`response_format`	objet	Transmis tel quel. Voir Outils et sortie JSON.
`tools`, `tool_choice`	tableau, chaîne ou objet	Transmis tels quels. Voir Outils et sortie JSON.
Tout autre champ		Ignoré. `n` vaut toujours 1.

Le corps d'une requête est limité à 2 Mo. Une valeur hors limites reçoit une erreur 400 avec le code invalid_parameter.

Comment s'appliquent les instructions de votre agent

Les instructions propres à votre agent sont toujours envoyées en premier, et un appel ne peut ni les supprimer ni les remplacer. Si vous envoyez des messages system (ou developer), leur texte est ajouté après les instructions de l'agent, sous l'intitulé « Additional instructions from the caller ». Servez-vous-en pour le contexte qui change d'un appel à l'autre, comme la langue de la réponse, la date du jour ou le nom d'un client.

Ajouter du contexte à un appel

reply = client.chat.completions.create(
    model="your-agent-id",
    messages=[
        {"role": "system", "content": "Répondez en anglais. Nous sommes le 26/09/2026."},
        {"role": "user", "content": "Collez ici le texte à traiter par votre agent."},
    ],
    max_tokens=400,
    temperature=0.2,
)

Les instructions intégrées accompagnent chaque appel. Elles comptent donc comme tokens d'entrée.

Outils et sortie JSON

response_format, tools et tool_choice parviennent à votre agent sans modification. Qu'une réponse respecte un format JSON ou appelle l'un de vos outils dépend de la façon dont votre agent a été conçu. Si votre intégration en dépend, dites-le-nous et nous le testerons avec vous.

Demander du JSON

import json

reply = client.chat.completions.create(
    model="your-agent-id",
    messages=[{"role": "user", "content": "Collez ici le texte à traiter par votre agent."}],
    response_format={"type": "json_object"},
)
data = json.loads(reply.choices[0].message.content)

Les appels d'outils arrivent dans choices[0].message.tool_calls, avec finish_reason à "tool_calls". Renvoyez chaque résultat dans un message de rôle tool, avec le tool_call_id correspondant.

Streaming

Passez "stream": true pour recevoir la réponse au fil de sa rédaction, sous forme de server-sent events. Chaque événement est une ligne qui commence par data: suivie d'un fragment JSON, et le flux se termine par data: [DONE].

stream = client.chat.completions.create(
    model="your-agent-id",
    messages=[{"role": "user", "content": "Collez ici le texte à traiter par votre agent."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:  # dernier fragment : nombre de tokens de toute la réponse
        print("\nTokens utilisés :", chunk.usage.total_tokens)

const stream = await client.chat.completions.create({
  model: "your-agent-id",
  messages: [{ role: "user", content: "Collez ici le texte à traiter par votre agent." }],
  stream: true,
  stream_options: { include_usage: true },
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  if (chunk.usage) console.log("\nTokens utilisés :", chunk.usage.total_tokens);
}

curl -N https://atelieragents.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-agent-id",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [{"role": "user", "content": "Collez ici le texte à traiter par votre agent."}]
  }'

À quoi ressemble le flux

data: {"id":"chatcmpl-7c1e","object":"chat.completion.chunk","created":1790000000,"model":"your-agent-id","choices":[{"index":0,"delta":{"content":"Total"},"finish_reason":null}]}

data: {"id":"chatcmpl-7c1e","object":"chat.completion.chunk","created":1790000000,"model":"your-agent-id","choices":[{"index":0,"delta":{"content":" à payer : 1 250,00"},"finish_reason":null}]}

data: {"id":"chatcmpl-7c1e","object":"chat.completion.chunk","created":1790000000,"model":"your-agent-id","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-7c1e","object":"chat.completion.chunk","created":1790000000,"model":"your-agent-id","choices":[],"usage":{"prompt_tokens":412,"completion_tokens":38,"total_tokens":450}}

data: [DONE]

Tokens et coût en streaming

Ajoutez "stream_options": {"include_usage": true} pour recevoir un dernier fragment avec un choices vide et le usage de toute la réponse. Si vous le demandez, il est envoyé à la fin de chaque flux, sauf quand le flux est interrompu (voir ci-dessous).
Une réponse en streaming ne peut pas porter les en-têtes X-Tokens-Used, X-Cost et X-Balance, car les en-têtes partent avant que la réponse soit écrite. Lisez le dernier fragment usage, ou appelez GET /v1/usage pour connaître votre solde.
Si vous fermez la connexion avant la fin, les tokens déjà générés sont facturés.
Un flux peut commencer par des lignes de commentaire (: keepalive) pendant que votre agent prépare sa réponse, et elles peuvent aussi arriver entre deux fragments. Les clients SSE et les SDK OpenAI les ignorent.
Si l'agent échoue avant le début du flux, vous recevez une erreur JSON classique avec un statut HTTP (voir Erreurs). S'il échoue une fois le flux commencé, celui-ci se termine par un événement d'erreur puis data: [DONE], sans fragment usage. Son code indique ce qui s'est passé. C'est upstream_unavailable, upstream_timeout ou server_busy quand aucun token n'a encore été envoyé (rien n'est facturé), upstream_interrupted quand votre agent a cessé de répondre en cours de route, ou internal_error pour une erreur inattendue de notre côté. Après une interruption, les tokens déjà produits sont facturés. Votre espace client et GET /v1/usage les affichent.

Un flux interrompu se termine ainsi

data: {"error":{"message":"The agent is temporarily unavailable. Please retry.","type":"server_error","code":"upstream_interrupted"}}

data: [DONE]

Endpoint /v1/run (mode simple)

POST https://atelieragents.com/v1/run

Le chemin le plus court depuis un outil no-code ou un script. Envoyez un texte, récupérez le résultat dans output, avec le coût de l'appel dans la même réponse.

Champs de la requête run
Champ	Type	Remarques
`input`	chaîne, objet ou tableau	La matière à traiter. Les objets et tableaux sont transmis à l'agent sous forme de texte JSON. Obligatoire, sauf si vous envoyez `messages`.
`messages`	tableau	À la place de `input`, au format chat completions.
`max_tokens`, `temperature`	entier, nombre	Facultatifs, mêmes règles que pour chat completions.

curl https://atelieragents.com/v1/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Collez ici le texte à traiter par votre agent."}'

import requests

response = requests.post(
    "https://atelieragents.com/v1/run",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"input": "Collez ici le texte à traiter par votre agent."},
    timeout=120,
)
response.raise_for_status()
print(response.json()["output"])

const response = await fetch("https://atelieragents.com/v1/run", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ input: "Collez ici le texte à traiter par votre agent." }),
});
const { output, usage, billing } = await response.json();

Réponse

{
  "id": "run_5f0c2a9e1b7d4c3a8e6f1d20",
  "object": "agent.run",
  "created": 1790000000,
  "agent": "your-agent-id",
  "output": "Total à payer : 1 250,00",
  "finish_reason": "stop",
  "usage": {
    "prompt_tokens": 412,
    "completion_tokens": 38,
    "total_tokens": 450
  },
  "billing": {
    "cost": "0.0054",
    "currency": "EUR",
    "included_tokens_used": 0,
    "included_tokens_remaining": 0,
    "balance": "42.0946"
  }
}

billing.cost et billing.balance sont des chaînes en EUR, included_tokens_remaining compte les tokens inclus restants sur votre période. Dans de rares cas, billing vaut null ; la réponse reste valable.
Le streaming, les outils et response_format ne sont pas disponibles ici. Utilisez chat completions pour en profiter.

Modèles

GET https://atelieragents.com/v1/models et /v1/models/{id}

La liste contient un seul modèle, l'agent que votre clé appelle. Son id est la valeur à envoyer dans model. /v1/models/{id} renvoie cette fiche, ou une erreur 404 model_not_found pour tout autre identifiant.

Requête

curl https://atelieragents.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Réponse

{
  "object": "list",
  "data": [
    {
      "id": "your-agent-id",
      "object": "model",
      "created": 1788000000,
      "owned_by": "atelier"
    }
  ]
}

Les endpoints models et usage répondent même quand votre solde est vide, votre compte suspendu ou votre agent en pause. Vos outils peuvent toujours vérifier où vous en êtes.

Consommation et solde

GET https://atelieragents.com/v1/usage

Votre solde, votre formule, vos tokens inclus et votre consommation du mois en cours, en un seul appel. Il ne vous coûte rien.

Requête

curl https://atelieragents.com/v1/usage \
  -H "X-API-Key: YOUR_API_KEY"

Réponse (valeurs d'exemple)

{
  "object": "usage",
  "agent": "your-agent-id",
  "plan": {
    "slug": "starter",
    "name": "Starter",
    "kind": "subscription"
  },
  "currency": "EUR",
  "balance": "42.10",
  "credit_limit": "0.00",
  "available": "42.10",
  "included_tokens_remaining": 3650000,
  "period_end": "2026-11-12T09:00:00Z",
  "rates": {
    "input_per_million": "10.00",
    "output_per_million": "10.00"
  },
  "month_to_date": {
    "since": "2026-10-01T00:00:00Z",
    "requests": 257,
    "prompt_tokens": 1042200,
    "completion_tokens": 307800,
    "total_tokens": 1350000,
    "cost": "0.00"
  },
  "portal": "https://atelieragents.com/portal",
  "generated_at": "2026-10-08T23:15:17Z"
}

Champs de la consommation
Champ	Signification
`balance`, `credit_limit`, `available`	Montants en EUR, sous forme de chaînes. `available` correspond à votre solde plus l'éventuelle ligne de crédit convenue avec nous.
`included_tokens_remaining`	Tokens inclus restants sur la période en cours (0 en paiement à l'usage).
`period_end`	Fin de la période en cours de votre formule, en UTC. `null` en paiement à l'usage.
`rates`	Votre prix par million de tokens d'entrée (`input_per_million`) et de tokens de sortie (`output_per_million`).
`month_to_date`	Appels, tokens et coût depuis le 1er du mois, en UTC.

En-têtes de réponse

En-têtes de facturation
En-tête	Signification	Exemple
`X-Tokens-Used`	Tokens d'entrée plus tokens de sortie de cet appel.	450
`X-Cost`	Coût de cet appel, en EUR.	0.0054
`X-Balance`	Votre solde après cet appel.	42.0946
`X-Included-Remaining`	Tokens inclus restants sur votre période.	0
`X-AI-Generated`	Chaque réponse est marquée comme générée par une IA, sous une forme lisible par un programme (aussi `"ai_generated": true` dans `/v1/run`).	true

Envoyés avec chaque réponse facturée hors streaming de /v1/chat/completions et /v1/run. Les navigateurs peuvent aussi les lire (ils sont exposés via CORS). Les montants suivent le format de l'API (point décimal), quelle que soit votre langue.

raw = client.chat.completions.with_raw_response.create(
    model="your-agent-id",
    messages=[{"role": "user", "content": "Collez ici le texte à traiter par votre agent."}],
)
print(raw.headers.get("x-cost"), raw.headers.get("x-balance"))
reply = raw.parse()  # l'objet ChatCompletion habituel

const { data: reply, response } = await client.chat.completions
  .create({ model: "your-agent-id", messages: [{ role: "user", content: "..." }] })
  .withResponse();
console.log(response.headers.get("x-cost"), response.headers.get("x-balance"));

Export de la consommation (CSV)

Le bouton Télécharger le CSV de la page Consommation de votre espace client donne une ligne par appel sur la période choisie. Depuis l'espace client en français, le fichier a des en-têtes en français, le point-virgule comme séparateur et la virgule décimale. Il s'ouvre directement en colonnes dans un tableur réglé en français. Depuis l'espace client en anglais, il suit le format anglais (virgules, point décimal, noms de colonnes techniques).

Colonnes du CSV de consommation
Colonne	Signification
Date et heure (UTC)	Le moment de l'appel, en heure UTC.
Agent	L'identifiant de votre agent, le nom de modèle que vous envoyez.
Endpoint	L'endpoint appelé, `chat.completions` pour `/v1/chat/completions` et `run` pour `/v1/run`.
Streaming	« oui » quand la réponse a été envoyée en streaming.
Code HTTP	Le statut HTTP de l'appel, `200` quand tout s'est bien passé, sinon voir Erreurs. `499` signifie que l'appelant a fermé le flux avant la fin. Les tokens déjà produits sont facturés.
Tokens d'entrée, Tokens de sortie, Total des tokens	Les tokens lus par votre agent, ceux qu'il a écrits, et les deux ensemble.
Tokens inclus	Les tokens couverts par le forfait de votre abonnement.
Tokens facturés	Les tokens payés sur votre solde.
Coût, Devise	Ce que l'appel a prélevé sur votre solde, et le code de la devise.
Latence (ms)	La durée de l'appel, en millisecondes.
Estimé	« oui » quand les décomptes de tokens ont été estimés.

Erreurs

Les erreurs suivent le format d'OpenAI. Les SDK les lèvent avec notre message, en anglais. Le champ code indique ce qui s'est passé.

HTTP 402

{
  "error": {
    "message": "Your balance is used up and no included tokens remain. Top up or change plan at https://atelieragents.com/portal",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

Codes d'erreur
Statut	Code	Signification	Que faire
400	`null`	Le corps est vide, n'est pas du JSON valide ou n'est pas un objet JSON.	Envoyez un objet JSON avec l'en-tête `Content-Type: application/json`.
400	`invalid_messages` `invalid_parameter` `invalid_input`	La requête est mal formée (aucun message, un message au mauvais format, une valeur hors limites).	Corrigez la requête. La renvoyer telle quelle échouera de nouveau.
400	`request_rejected`	Votre agent n'a pas pu traiter l'entrée, le plus souvent parce qu'elle est trop longue. Non facturé.	Envoyez moins de texte, ou réduisez `max_tokens`.
400	`unsupported_request`	Votre requête utilise un élément que cet agent ne sait pas traiter, par exemple un type de contenu ou une définition d'outil non prise en charge. Le message indique lequel. Non facturé.	Retirez ou modifiez cet élément de la requête.
401	`invalid_api_key`	La clé est absente, mal saisie ou révoquée.	Vérifiez l'en-tête. Demandez-nous une nouvelle clé si besoin.
402	`insufficient_quota`	Votre solde est épuisé et il ne reste aucun token inclus, ou des appels encore en cours utilisent déjà ce qui reste.	Rechargez votre solde ou changez de formule dans votre espace client. Si d'autres appels étaient en cours, réessayez quand ils sont terminés ; sinon, réessayer ne sert à rien avant une recharge.
403	`account_suspended` `agent_paused`	Votre compte est suspendu, ou cet agent est en pause.	Contactez-nous.
404	`model_not_found`	Sur `/v1/models/{id}`, cet identifiant n'est pas celui de votre agent. Les chemins inconnus reçoivent aussi une 404.	Utilisez l'identifiant renvoyé par `/v1/models`.
413	`request_too_large`	Le corps dépasse 2 Mo.	Envoyez moins par appel, en découpant les longs documents.
429	`rate_limit_exceeded`	Trop d'appels avec cette clé au cours de la dernière minute.	Attendez le nombre de secondes indiqué dans `Retry-After`, puis réessayez.
500	`null`	Une erreur inattendue de notre côté.	Réessayez avec un délai croissant.
502	`upstream_unavailable`	Votre agent est momentanément indisponible. Non facturé.	Réessayez avec un délai croissant.
503	`server_busy`	Votre agent est occupé en ce moment (trop d'appels à la fois). Non facturé.	Attendez le nombre de secondes indiqué dans `Retry-After` (de 1 à 60), puis réessayez.
503	`agent_backend_unavailable`	Le serveur d'IA propre à votre agent, ainsi que tout serveur de secours prévu pour lui, sont indisponibles en ce moment (arrêtés ou en dehors de leurs heures d'ouverture). La demande n'a été envoyée nulle part ailleurs. Non facturé.	Traitez l'élément comme à vérifier à la main, ou réessayez plus tard. Quand l'un d'eux ouvre à heures fixes, `Retry-After` indique le nombre de secondes avant son ouverture.
504	`upstream_timeout`	Votre agent a mis trop de temps à répondre. Non facturé.	Réessayez, ou réduisez `max_tokens` et envoyez moins de texte.

Nous vérifions d'abord la taille du corps, puis la clé, le statut du compte et de l'agent, le solde, la limite de débit, la disponibilité du serveur d'IA de votre agent, et enfin le contenu de la requête. Avant une erreur 502, 503 ou 504, nous avons parfois déjà relancé votre appel une fois de notre côté. Patientez un instant avant de réessayer.

Limites de débit

Vos clés n'ont aucune limite d'appels par minute, sauf si nous en avons convenu une avec vous. Un gros traitement par lots ou un agent très sollicité n'est donc jamais ralenti par un compteur. Votre solde s'applique toujours, et votre espace client affiche la limite éventuelle à côté de chaque clé. Lorsqu'une clé a une limite, la fenêtre est glissante et compte les appels des 60 dernières secondes.

Au-delà de la limite d'une clé qui en a une, un appel reçoit une erreur 429 avec un en-tête Retry-After, en secondes.
/v1/models et /v1/usage ont leur propre compteur, avec la même limite. Consulter votre solde n'entame jamais votre quota d'appels.
Aux heures chargées, un appel peut attendre quelques secondes avant que votre agent ne le prenne en charge. Si aucune place ne se libère à temps, il reçoit une erreur 503 server_busy avec un en-tête Retry-After, et rien n'est facturé.

Tokens et facturation

Vous payez des tokens, c'est-à-dire des morceaux de mots (un token, environ 3/4 d'un mot). Chaque appel en compte deux sortes.

Les tokens d'entrée, tout ce que votre agent lit, c'est-à-dire vos messages plus ses instructions intégrées.
Les tokens de sortie, tout ce qu'il écrit.

Vos tarifs dépendent de votre formule. Consultez les tarifs, ou votre espace client pour vos propres chiffres.

Cela concerne les agents que nous faisons tourner pour vous. Un agent en achat unique vous est livré et fonctionne chez vous. Ses frais d'utilisation sont ceux de votre propre compte chez un fournisseur d'IA ou de votre serveur.

Exemple

Tokens d'entrée: 1 500
Tokens de sortie: 500
Tarif, paiement à l'usage: 12,00 € le million
Coût de l'appel: 0,024 €
Calcul: 2 000 × 12,00 € / 1 000 000

Comment un appel est facturé

D'abord les tokens inclus. Avec un abonnement, les tokens d'entrée puis de sortie sont déduits de votre forfait mensuel. Les tokens inclus non utilisés expirent à la fin de chaque période.
Ensuite votre solde. Les tokens au-delà du forfait, ou tous les tokens en paiement à l'usage, sont payés sur votre solde prépayé, aux tarifs par million de tokens de votre formule.
Arrondi au supérieur, appel par appel, au millionième d'unité monétaire (0,000001 €). Vos totaux sont la somme exacte de vos appels.

Quand le solde est épuisé

Les appels sont acceptés tant qu'il vous reste des tokens inclus, ou tant que votre solde, plus l'éventuelle ligne de crédit convenue, est supérieur à zéro. Le dernier appel peut faire passer le solde légèrement sous zéro ; le suivant reçoit une erreur 402 insufficient_quota.

Les appels en cours comptent déjà sur votre solde. Quand il est presque épuisé, des appels parallèles peuvent recevoir une erreur 402 insufficient_quota avant la fin du premier. Réessayez quand ils sont terminés.

Avec un abonnement payé en ligne, les appels continuent de passer jusqu'à 7 jours après la fin de la période, le temps que le renouvellement soit réglé. Une fois le paiement reçu, ils sont décomptés de la nouvelle période.

Quand l'argent dont vous disposez (votre solde plus l'éventuelle ligne de crédit) passe sous 2,00 €, nous vous envoyons un e-mail, une seule fois. L'alerte se réarme après une recharge.

Décomptes estimés

Si votre agent ne communique pas le nombre exact de tokens d'un appel, nous l'estimons à partir de la longueur du texte, à raison d'environ 4 caractères par token. Ces appels sont marqués « estimé » dans votre espace client et dans l'export CSV de votre consommation.

Exemples avec les SDK

Tout client compatible OpenAI fonctionne. Réglez son URL de base sur https://atelieragents.com/v1 et le modèle sur l'identifiant de votre agent.

from openai import OpenAI

client = OpenAI(
    base_url="https://atelieragents.com/v1",
    api_key="YOUR_API_KEY",
)

reply = client.chat.completions.create(
    model="your-agent-id",
    messages=[{"role": "user", "content": "Collez ici le texte à traiter par votre agent."}],
)
print(reply.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://atelieragents.com/v1",
  apiKey: "YOUR_API_KEY",
});

const reply = await client.chat.completions.create({
  model: "your-agent-id",
  messages: [{ role: "user", content: "Collez ici le texte à traiter par votre agent." }],
});
console.log(reply.choices[0].message.content);

const response = await fetch("https://atelieragents.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "your-agent-id",
    messages: [{ role: "user", content: "Collez ici le texte à traiter par votre agent." }],
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(data.error.message);
console.log(data.choices[0].message.content);

curl https://atelieragents.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-agent-id",
    "messages": [
      {"role": "user", "content": "Collez ici le texte à traiter par votre agent."}
    ]
  }'

Bibliothèques
Langage	Installation	Réglage
Python	`pip install openai`	`OpenAI(base_url=..., api_key=...)`
JavaScript, TypeScript	`npm install openai`	`new OpenAI({ baseURL, apiKey })`
Autre langage	N'importe quel client HTTP	Requête POST en JSON avec l'en-tête de la clé

Outils no-code

Make, Zapier, n8n et les outils similaires appellent votre agent avec leur étape de requête HTTP. Utilisez l'endpoint /v1/run (mode simple) avec les réglages ci-dessous.

Réglages de la requête HTTP

Méthode       POST
URL           https://atelieragents.com/v1/run
En-tête       Authorization: Bearer YOUR_API_KEY
En-tête       Content-Type: application/json
Corps (JSON)  {"input": "insérez ici le texte issu de l'étape précédente"}
Résultat      lisez le champ "output" de la réponse

Où trouver l'étape HTTP
Outil	Étape à utiliser	Remarques
Make	HTTP, « Make a request »	Type de corps raw, type de contenu JSON. Activez l'analyse de la réponse, puis reprenez `output` dans le module suivant.
Zapier	Webhooks by Zapier, « Custom Request »	Méthode POST, le JSON dans Data, les deux en-têtes dans Headers. La réponse se trouve dans `output`.
n8n	Nœud HTTP Request	Méthode POST, envoi d'un corps JSON, ajout de l'en-tête Authorization (ou d'un identifiant de type en-tête). Lisez `output`.

Les libellés varient d'une version à l'autre de ces outils ; les réglages ci-dessus restent les mêmes.
Quand vous insérez un champ dans le corps JSON, vérifiez que les guillemets et les retours à la ligne du texte sont échappés. La plupart des outils proposent une insertion compatible JSON.
Beaucoup d'outils cessent d'attendre au bout de 30 à 60 secondes. Ajoutez "max_tokens": 400 (ou la valeur dont vous avez besoin) au corps pour garder des appels courts.

Bonnes pratiques

Gardez des prompts courts. Votre agent connaît déjà son travail. Envoyez la matière à traiter, pas de longues consignes, car vous payez chaque token qu'il lit.
Plafonnez max_tokens à la plus longue réponse dont vous avez besoin. Cela borne à la fois le coût et la durée de chaque appel.
Réessayez avec un délai croissant en cas de 429, 500, 502, 503 et 504, en respectant Retry-After. Ne réessayez pas une 400, 401, 402 ou 403.
Fixez un délai d'attente côté client d'une à deux minutes, ou passez en streaming pour les longues réponses.
Surveillez votre solde. Lisez X-Balance, ou appelez /v1/usage avant un gros traitement par lots.
Une clé par intégration, tenue à l'écart du code front-end et du contrôle de version.

from openai import OpenAI

client = OpenAI(
    base_url="https://atelieragents.com/v1",
    api_key="YOUR_API_KEY",
    max_retries=5,  # relance les 429 et 5xx avec un délai croissant et respecte Retry-After
    timeout=120,    # secondes : les longues réponses prennent du temps
)

async function callAgent(body, attempts = 5) {
  for (let attempt = 0; ; attempt++) {
    const response = await fetch("https://atelieragents.com/v1/chat/completions", {
      method: "POST",
      headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
      body: JSON.stringify(body),
    });
    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable || attempt >= attempts - 1) return response;
    const wait = Number(response.headers.get("retry-after")) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
}

Historique des versions

Appels en attente et documentation en français
Aux heures chargées, un appel attend quelques secondes qu'une place se libère ; sinon il reçoit une erreur 503 server_busy avec Retry-After. Cette documentation est désormais disponible en français.
28 sept. 2026
API v1
Chat completions avec streaming et fragment final de consommation, endpoint /v1/run en mode simple, modèles, consommation et solde, en-têtes de facturation sur chaque réponse hors streaming.
26 sept. 2026

Nous ajoutons des champs aux réponses au fil du temps. Ignorez ceux que vous n'utilisez pas, et votre intégration continuera de fonctionner.