Référence de l’API

Référence complète de l’API HTTP pour l’endpoint d’évaluation de TypeSafe.

Évalue un state par rapport à une association de questions typées et récupère des answers structurées, une par question. Pour une introduction guidée, commence par les primitives.

Endpoint d’évaluation

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

Corps de la requête

La forme de premier niveau de chaque requête. Chaque entrée de l’association questions est une question typée que tu nommes.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}

Types de question

Une Question est de l’un des trois types, fixé par son champ type. Les trois partagent type et instructions ; chacune ajoute ses propres criteria.

La propriété instructions peut être une chaîne, un objet ou un tableau. Tu peux découper une question longue qui comporte du contexte supplémentaire, ou des données qu’elle doit référencer, en un objet structuré. Place la question dans un champ et les données dans les autres, et désigne les champs de données par leur nom entre accents graves, comme tu pointes une question vers une valeur state imbriquée :

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

Voir Utiliser une structure dans les questions pour en savoir plus.

Noul

Une question oui/non. Renvoie la probabilité que la réponse soit oui.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": {
        "true": "Explicitly time-sensitive",
        "false": "No urgency expressed"
      }
    }
  }
}

Choice

Choisit une option dans un ensemble que tu définis. Renvoie l’option choisie et la distribution de probabilité complète.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Score

Note l’état selon une grille que tu définis. Renvoie une valeur pondérée par les probabilités sur tes niveaux.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

Corps de la réponse

Une réponse par question, renvoyée sous les mêmes id que ceux que tu as fournis.

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

Types de réponse

Chaque réponse porte un type correspondant à sa question. Les réponses Choice et Score portent aussi une confidence entre 0 et 1, dérivée de la distribution de probabilité de la réponse. Voir Confiance.

Réponse Noul

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

Réponse Choice

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

Réponse Score

{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

Erreurs

Les erreurs utilisent les codes de statut HTTP standard avec un corps JSON décrivant ce qui n’a pas fonctionné.

Gestion des limites de débit

Quand tu reçois une réponse 429 Too Many Requests ou 529 Overloaded, réessaie la requête avec un backoff exponentiel plutôt qu’immédiatement. Nos SDK clients gèrent cela automatiquement, donc aucun traitement supplémentaire n’est nécessaire si tu utilises l’un de nos SDK avec sa politique de réessai par défaut.