Référence des outils
Les entrées, valeurs valides, forme de sortie et erreurs possibles de chaque appel, pour chaque outil intégré — la référence complète derrière les guides de démarrage rapide.
Les guides précédents vous amènent rapidement à un appel fonctionnel. Cette page est la référence à laquelle vous revenez une fois que vous intégrez pour de bon : les entrées et valeurs valides de chaque outil, ce que chacun produit en sortie, et exactement quelles erreurs vous pouvez obtenir en retour — séparées selon que vous appelez anonymement ou avec une clé, car ces deux chemins se comportent différemment.
Les outils
Tous les outils ci-dessous sont appelables anonymement (sans clé API, avec limitation de débit) via le modèle décrit dans Votre premier appel SDK, et ce sont ceux affichés sur la page publique des outils. Ils sont aussi appelables de façon authentifiée (clé API/JWT) — voir Obtenez votre clé API et Choisissez votre mode d’authentification.
Outil (pipeline) | Crédits |
|---|---|
translate | 1 |
summarize | 1 |
rewrite | 1 |
grammar-fix | 1 |
email-generator | 2 |
knowledge-base-qa | 2 |
Les crédits représentent le coût réel d’un appel sur votre plan/portefeuille — vérifiez le nombre avant de construire une fonctionnalité autour d’un outil.
translate
| Entrée | Type | Obligatoire | Valeurs valides | Notes |
|---|---|---|---|---|
text | string | oui | jusqu’à 5000 caractères | Le texte source. La langue est détectée automatiquement — vous ne spécifiez pas de langue source. |
target_language | string | oui | en, es, de, ja, fr, pt, zh-Hans, zh-Hant, ko, ar, vi, th, ms | Le code de la langue vers laquelle traduire. |
glossary_inline | string | non | jusqu’à 4000 caractères | Substitutions de termes optionnelles, une paire par ligne au format source=target ou source,target. Non stocké — s’applique uniquement à cet appel. |
Sortie : translation (le texte traduit), applied_terms (quels termes du glossaire, le cas
échéant, ont été appliqués).
const out = await ai.run({
pipeline: "translate-string",
inputs: { text: "Hello", target_language: "de" },
});
// out.translation === "Hallo"
summarize
| Entrée | Type | Obligatoire | Valeurs valides | Notes |
|---|---|---|---|---|
text | string | oui | jusqu’à 5000 caractères | Le texte source à résumer. |
length | string | non | short, medium, long | Omettez pour la longueur par défaut. |
language | string | non | "" (conserver l’original) ou tout code du tableau translate ci-dessus | Langue de sortie. Une chaîne vide conserve la langue du texte source. |
extract | string[] | non | action_items, decisions, risks, timeline | Zéro ou plusieurs sections structurées supplémentaires. Envoyez-les dans cet ordre exact — un ordre différent compte comme une requête différente pour la mise en cache, même si les valeurs sont par ailleurs identiques. |
Sortie : tldr, key_points, et celles parmi action_items / decisions / risks /
timeline que vous avez demandées dans extract.
rewrite
| Entrée | Type | Obligatoire | Valeurs valides | Notes |
|---|---|---|---|---|
text | string | oui | jusqu’à 5000 caractères | Le texte source à réécrire. |
action | string | non | rephrase, shorten, expand, simplify, formalize, bulletize | L’opération de réécriture. |
tone | string | non | professional, casual, friendly, concise | Le ton cible. |
language | string | non | "" (conserver l’original) ou tout code du tableau translate ci-dessus | Langue de sortie. |
glossary_inline | string | non | jusqu’à 4000 caractères | Même format que le glossary_inline de translate ci-dessus. |
Sortie : rewrite (le texte réécrit), applied_terms.
grammar-fix
| Entrée | Type | Obligatoire | Valeurs valides | Notes |
|---|---|---|---|---|
text | string | oui | jusqu’à 5000 caractères | Le texte source à corriger. |
glossary_inline | string | non | jusqu’à 4000 caractères | Même format que le glossary_inline de translate ci-dessus. |
Sortie : corrected (le texte corrigé), changes (une liste de ce qui a changé),
applied_terms.
email-generator
| Entrée | Type | Obligatoire | Valeurs valides | Notes |
|---|---|---|---|---|
purpose | string | oui | jusqu’à 2000 caractères | Le sujet de l’email et ce qu’il doit couvrir. |
recipient | string | non | jusqu’à 500 caractères | À qui il est adressé. Omettez pour un destinataire générique. |
tone | string | non | formal, friendly, persuasive | Le ton de l’email rédigé. |
glossary_inline | string | non | jusqu’à 4000 caractères | Même format que le glossary_inline de translate ci-dessus. |
Sortie : subject, body, applied_terms.
knowledge-base-qa
| Entrée | Type | Obligatoire | Valeurs valides | Notes |
|---|---|---|---|---|
question | string | oui | jusqu’à 1000 caractères | La question à laquelle répondre. |
context | string | oui | jusqu’à 6000 caractères | Le document unique sur lequel la réponse doit être fondée. |
Sortie : answer, grounded (si la réponse est réellement étayée par context), citation
(d’où dans context provient la réponse).
Il n’y a aucun index de recherche ni de connaissance externe derrière cet outil — il ne répond
jamais qu’à partir du texte context de la même requête. Pour tout ce qui dépasse un seul document
d’environ 6000 caractères, découpez votre texte source et appelez l’outil par morceau.
Erreurs
Les erreurs que vous pouvez obtenir en retour dépendent de la façon dont vous appelez — les appels anonymes et authentifiés sont validés différemment. Ne supposez pas que le comportement d’erreur d’un chemin s’applique à l’autre.
Appel anonyme (sans clé API)
Le modèle de Votre premier appel SDK — tous les outils listés ci-dessus, avec limitation de débit par IP.
| Statut | Code d’erreur | Signification |
|---|---|---|
| 404 | — | Slug d’outil inconnu. |
| 403 | — | Échec de la vérification anti-bot. |
| 429 | guest_quota_exceeded | Vous avez atteint la limite quotidienne de requêtes anonymes, par IP ou globale. |
| 429 | guest_cost_exceeded | Vous avez atteint la limite quotidienne de coût anonyme, par IP ou globale (les outils coûteux épuisent ce budget plus vite). |
| 202 | — | Succès — { ticket_id, status: "QUEUED" }. Effectuez le polling du résultat comme pour tout autre appel. |
Important : sur ce chemin, vos inputs ne sont pas vérifiées par rapport aux tableaux ci-dessus
avant que l’appel soit accepté — un champ obligatoire manquant ou une valeur invalide ne vous vaut
pas une erreur 400. C’est l’exécution elle-même qui échouera à la place, ce que vous verrez en
faisant le polling du résultat. Une fois que vous avez une clé API, passez au chemin authentifié
ci-dessous, qui valide en amont.
Appel avec une clé API ou un token de session
Le modèle de Choisissez votre mode d’authentification — l’un quelconque des outils auxquels vous avez accès.
| Statut | Code d’erreur | Signification |
|---|---|---|
| 401 | — | Identifiants manquants, invalides, ou expirés. |
| 403 | app_disabled | Votre application a été désactivée. |
| 403 | org_suspended | Votre organisation a été suspendue. |
| 403 | org_pending_deletion | Votre organisation est programmée pour suppression. |
| 403 | — | Cet outil ne fait pas partie de la liste des pipelines autorisés de vos identifiants. |
| 400 | — | Vos inputs ne correspondent pas aux exigences de l’outil (champ obligatoire manquant, valeur invalide, ou entrée totale trop volumineuse). Ce chemin valide bien en amont, contrairement au chemin anonyme. |
| 429 | rate_limited | Vous envoyez des requêtes plus vite que votre limite par minute. |
| 429 | quota_exceeded | Vous avez atteint votre quota mensuel de requêtes. |
| 429 | daily_cost_exceeded | Vous avez atteint un plafond de coût quotidien — une limite de vélocité, distincte du fait de manquer de solde ci-dessous. |
| 402 | insufficient_credits | Le solde de crédits de votre organisation est trop faible pour couvrir cet appel. Rechargez et réessayez. |
| 202 | — | Succès — { ticket_id, status: "QUEUED" }. Effectuez le polling du résultat. |
Pour en savoir plus sur le fonctionnement des identifiants et des décisions d’authentification 401/403/429, voir Choisissez votre mode d’authentification.