Documentation

Créez une clé d’API, activez la facturation à l’usage et envoyez votre première requête. Crossroads répond à des questions typées sur un contexte; il ne rédige pas de texte, ne tient pas de conversation et ne remplace pas le modèle d’un agent de programmation.

Vous travaillez avec un agent de programmation ? Demandez-lui d’installer Crossroads avec smallmodelslab.ai/agents.md.

Envoyer une requête

Remplacez l’hôte par votre déploiement Crossroads et gardez votre clé d’API sur le serveur. Utilisez une clé d’idempotence unique pour chaque requête distincte.

curl "$CROSSROADS_URL/v1/decisions" \
  -H "Authorization: Bearer $CROSSROADS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-123-attempt-1" \
  -d '{
  "state": "Hi! We were charged twice for our team's plan this month. Could you help us sort this out?",
  "questions": {
    "route": {
      "type": "choice",
      "instruction": "Which team should handle this request?",
      "options": [
        "billing",
        "engineering",
        "sales"
      ]
    },
    "needs_reply": {
      "type": "boolean",
      "instruction": "Does this message need a reply?"
    },
    "urgency": {
      "type": "score",
      "instruction": "How urgent is this request?",
      "min": 1,
      "max": 5
    }
  }
}'

Lire la réponse

Chaque réponse porte les probabilités du modèle : pour un booléen, la probabilité de vrai; pour un choix, une par option; pour un score, une par niveau.

{
  "id": "5f1c…",
  "model": "crossroads-8b",
  "answers": {
    "route": {
      "choice": "billing",
      "probabilities": {
        "billing": 0.91,
        "engineering": 0.06,
        "sales": 0.03
      }
    },
    "needs_reply": {
      "value": true,
      "probability": 0.94
    },
    "urgency": {
      "score": 3.48,
      "probabilities": {
        "1": 0.02,
        "2": 0.08,
        "3": 0.41,
        "4": 0.38,
        "5": 0.11
      }
    }
  },
  "usage": {
    "input_tokens": 96,
    "output_tokens": 0
  }
}

Types de questions

Filtrer une liste

POST /v1/filter reçoit jusqu’à 256 éléments JSON, chacun d’au plus 48 000 caractères en JSON ou 16 000 sur Crossroads-M, et une consigne d’au plus 1 800 caractères. Il renvoie les éléments dont la probabilité de correspondre atteint cutoff (0,5 par défaut), du plus probable au moins probable, avec leurs probabilités et leurs positions dans votre liste. model, image et audio fonctionnent comme pour les décisions : chaque élément est jugé par rapport à l’image ou à l’enregistrement. Réutiliser la clé d’idempotence en ne changeant que cutoff reclasse les probabilités enregistrées sans nouvelle facturation. Une longue liste est traitée par lots facturés un à un : une nouvelle clé après un filtre échoué facture de nouveau ses lots terminés.

curl "$CROSSROADS_URL/v1/filter" \
  -H "Authorization: Bearer $CROSSROADS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: billing-filter-1" \
  -d '{
  "items": [
    {
      "title": "Fix invoices"
    },
    {
      "title": "Update landing page"
    }
  ],
  "instruction": "Keep billing work",
  "cutoff": 0.8
}'

Modèles

Crossroads 8B coûte 0,040 $US et Crossroads M 0,080 $US par million de jetons d’entrée; la sortie est gratuite. Chaque question est évaluée sur tout le state : les jetons d’entrée d’une requête comptent, pour chaque question, le state, sa consigne et ses options, ainsi que l’image ou l’enregistrement. Seize questions dans une requête coûtent autant que seize requêtes, mais ne font qu’un aller-retour et ne comptent qu’une fois dans vos limites.

Une requête avec un enregistrement est traitée par le modèle entraîné sur l’audio, conçu pour les commandes vocales, les mots-clés, la langue parlée, la distinction entre parole, musique et bruit, et l’intention exprimée à l’oral; l’émotion, les sons ambiants et l’analyse musicale ne sont pas pris en charge.

Rédiger le state

Le state est ce sur quoi porte chaque question : un message, un document, ou un objet ou un tableau JSON d’enregistrements liés. Préférez un objet dont les noms disent ce qu’est chaque partie, et reprenez ces noms dans les consignes. Placez dans un même state tout ce qu’une question doit comparer, comme une demande et la politique qui permet d’en juger. Laissez de côté ce dont aucune question n’a besoin : cela coûte des jetons à chaque question et peut induire le modèle en erreur.

{
  "message": "I was charged twice for order A-104. Please refund the duplicate.",
  "order": {
    "id": "A-104",
    "charges": [
      { "amount_usd": 49, "status": "captured" },
      { "amount_usd": 49, "status": "captured" }
    ]
  },
  "refund_policy": "Duplicate charges are refunded in full."
}

Agir selon les probabilités

Les probabilités disent à quel point le modèle est sûr. Agissez sur une réponse quand sa probabilité est élevée, demandez une confirmation ou une vérification entre les deux, et confiez le cas à une personne ou à un autre système quand elle est faible. Fixez chaque seuil selon le coût d’une erreur : émettre un remboursement mérite un seuil plus élevé qu’étiqueter un ticket.

const { choice, probabilities } = answers.route;
if (probabilities[choice] >= 0.9) assign(choice);
else if (probabilities[choice] >= 0.6) suggest(choice);
else sendToPerson();

Un choix dont les probabilités sont proches, ou un score réparti sur plusieurs niveaux, signale souvent des options qui se recoupent, des niveaux ambigus ou un state qui manque de ce qu’il leur faut; reformulez-les avant d’abaisser un seuil. La sortie typée contraint le format, pas le jugement, et les probabilités ne sont pas garanties calibrées : choisissez vos seuils à partir de vos propres exemples annotés.

Schémas d’intégration

Limites

Envoyez du JSON UTF-8 avec Content-Type: application/json; les champs inconnus sont refusés. Une requête contient de 1 à 16 questions nommées et jusqu’à 48 000 caractères de state, en texte ou en JSON compté sous sa forme compacte, et pèse au plus 1,5 Mio. Crossroads-M accepte aussi une image (JPEG, PNG ou WebP) ou un enregistrement (WAV ou FLAC, 30 secondes au plus), chacun limité à 1 Mio en base64 complété; avec un enregistrement, state peut être vide. Par défaut, chaque compte peut envoyer 120 requêtes par minute et quatre à la fois.

Erreurs et nouvelles tentatives

Chaque erreur comprend un code, un message descriptif et un identifiant de requête; conservez cet identifiant lorsque vous signalez un problème. La même entrée avec la même clé d’idempotence renvoie la réponse enregistrée sans nouvelle facturation : réessayer avec la même clé est donc toujours sûr.

Données et facturation

Crossroads conserve l’empreinte de la requête, les réponses renvoyées et l’utilisation des jetons pour les nouvelles tentatives et la facturation. Il ne conserve ni l’état fourni ni les consignes des questions. La politique de confidentialité décrit ce qui est conservé d’autre et qui le traite.

Seules les réponses validées et enregistrées avec succès entrent dans le registre de facturation, avec leur utilisation.