Mode raw prompt

Envoyez un prompt système/utilisateur personnalisé directement au modèle au lieu d'un pipeline nommé — forme de la requête, choix du modèle, et les contraintes qui ne s'appliquent pas aux pipelines nommés.

Tous les autres guides de cette section appellent un pipeline nommé (translate-string, summarize, etc.) — un modèle de prompt fixe avec des entrées déclarées. Le mode raw court-circuite le modèle : vous envoyez directement votre propre system_prompt et user_prompt, et la plateforme les exécute tels quels. Utilisez-le pour prototyper un prompt avant qu’il ne vaille la peine d’être transformé en véritable pipeline, ou pour un appel ponctuel qui ne correspond à aucun des outils intégrés.

L’activer

Le mode raw est verrouillé séparément des pipelines nommés. La claim pipelines[] de votre JWT a besoin d’une entrée explicite "raw" — la même claim que celle utilisée pour les identifiants de pipelines nommés, avec juste cette chaîne supplémentaire. Elle n’est pas accordée par défaut, et la plupart des tokens de session d’utilisateur final ne devraient jamais l’avoir : le coût d’un pipeline nommé est borné par son modèle, mais le coût d’un prompt raw n’est borné que par la longueur du prompt que vous êtes prêt à envoyer et le nombre de tokens que vous demandez au modèle de générer.

Si votre application crée elle-même des session tokens (voir la section POST /auth/token d’Intégration serveur Node.js), demandez "raw" uniquement pour les tokens spécifiques qui en ont besoin — par exemple un outil d’administration interne, pas les tokens remis à des utilisateurs finaux arbitraires. Demandez à votre opérateur de plateforme de confirmer que le allowed_pipelines de votre Application inclut "raw" avant de demander un token avec cette claim ; une claim que votre Application n’est pas autorisée à accorder est silencieusement retirée du token émis.

Une x-api-key statique (non liée, à portée opérateur — voir Obtenez votre clé API) contourne entièrement la vérification de la liste des pipelines, tout comme pour les pipelines nommés. Une x-api-key émise par la Console et liée à une application, ainsi qu’un appelant JWT/webtoken, ont tous deux besoin de l’octroi explicite "raw".

L’appeler — SDK

const out = await ai.run({
  raw: {
    system_prompt: "You are a terse assistant. Answer in one sentence.",
    user_prompt: "What does raw mode skip that a named pipeline has?",
    model: "gpt-5-mini",   // optional — see "Choosing a model" below
    temperature: 0.2,       // optional
    max_tokens: 500,        // optional, up to 32768
  },
});
console.log(out.text);

user_prompt peut aussi être une fonction de inputs lorsqu’il est utilisé avec ai.runMany(...) — voir le guide d’intégration complet du SDK (demandez-en une copie à votre opérateur de plateforme — il n’est pas public) pour ce schéma. ai.button(...) accepte aussi une config raw à la place de pipeline.

L’appeler — HTTP direct

Nécessite Authorization: Bearer <jwt> avec l’octroi "raw" (une x-api-key statique fonctionne aussi si c’est le type non lié, à portée opérateur — voir ci-dessus). params est optionnel et les deux champs qu’il contient sont optionnels :

curl -X POST "https://api.quravin.com/tickets" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt>" \
  -d '{
    "mode": "raw",
    "system_prompt": "You are a terse assistant. Answer in one sentence.",
    "user_prompt": "What does raw mode skip that a named pipeline has?",
    "model": "gpt-5-mini",
    "params": { "temperature": 0.2, "max_tokens": 500 }
  }'

Réponse (202), puis effectuez le polling comme pour tout autre ticket — voir Intégration API directe si vous n’avez pas encore construit cette boucle :

{ "ticket_id": "01J...ULID", "status": "QUEUED" }

curl "https://api.quravin.com/tickets/01J...ULID" \
  -H "Authorization: Bearer <your-jwt>"

Réponse une fois terminé — la forme est toujours les quatre mêmes champs plus text, quel que soit le modèle qui a exécuté l’appel :

{
  "ticket_id": "01J...ULID",
  "status": "DONE",
  "mode": "raw",
  "result": {
    "text": "It skips the fixed prompt template and declared input schema.",
    "model": "gpt-5-mini",
    "latency_ms": 640,
    "tokens_in": 38,
    "tokens_out": 14
  },
  "created_at": "2026-07-10T12:00:00.000Z",
  "updated_at": "2026-07-10T12:00:02.000Z"
}

Il n’y a aucun champ propre à un pipeline à rechercher (pas de translation, pas de tldr) — result.text est toujours l’endroit où atterrit la sortie du modèle.

Choisir un modèle

model est optionnel — omettez-le pour utiliser le modèle par défaut actuel de la plateforme. Si vous le définissez explicitement, il doit s’agir d’un modèle pour lequel la plateforme a un tarif de coût vérifié, vérification effectuée avant que l’appel n’atteigne le LLM : envoyez autre chose et vous obtenez 400 invalid_model au lieu d’une facture surprise. Au moment de l’écriture, cette liste est gpt-4o-mini, gpt-4o, o3, et gpt-5-mini — demandez à votre opérateur de plateforme la liste actuelle, car elle évolue à mesure que des modèles sont ajoutés.

Ce qui diffère d’un pipeline nommé

Pas de schéma d’entrée. Un pipeline nommé valide vos inputs par rapport à son schéma déclaré avant que l’appel soit accepté (champ manquant, mauvais type → 400). Le mode raw n’a aucun schéma — system_prompt et user_prompt sont des chaînes obligatoires, mais leur contenu n’est jamais validé. Un prompt qui n’a pas de sens pour le modèle n’échoue pas en amont ; le ticket s’exécute, et vous le découvrez en faisant le polling du résultat.
Pas de mise en cache. Les pipelines nommés mettent en cache les appels identiques selon leurs entrées. Le mode raw ne vérifie jamais de cache — chaque appel est un nouvel appel au modèle, à chaque fois, même si vous envoyez exactement le même prompt deux fois de suite.
Le filet de sécurité global sur la taille des entrées s’applique toujours, mesuré différemment : system_prompt.length + user_prompt.length combinés doivent rester sous le plafond de caractères de la plateforme (50 000 par défaut) — la même limite de défense en profondeur qui borne les inputs d’un pipeline nommé, simplement additionnée sur les deux champs au lieu du corps JSON entier.
max_tokens est plafonné à 32768 quoi que le modèle sous-jacent autoriserait sinon — un plafond sur le pire cas d’un seul appel, pas une cible à viser.

Erreurs

Le même tableau d’erreurs du chemin authentifié que tout autre appel — voir Intégration API directe pour la liste complète. Une erreur est spécifique au mode raw : 400 invalid_model, couverte ci-dessus.

Si votre JWT ne porte pas l’octroi "raw", vous obtenez le même 403 que pour l’appel d’un pipeline nommé que vous n’êtes pas autorisé à utiliser — voir Choisissez votre mode d’authentification pour savoir comment fonctionnent les octrois d’identifiants.