Votre premier appel à l'API IA

L'API IA permet à vos propres logiciels d'exécuter des applications d'IA : vous désignez une application, vous envoyez les valeurs de ses champs d'entrée, et vous relisez la réponse du modèle une fois l'exécution terminée. C'est une API JSON sur HTTPS. Vous vous authentifiez avec la clé de votre projet IA, vous appelez un chemin sous /v1/ai/ et vous lisez le résultat dans une enveloppe de réponse unique.

Avant de commencer — Il vous faut la clé API de votre projet IA (elle commence par sk-project-). Il n'y a pas d'inscription en libre-service : l'équipe Ultineo ouvre votre projet et vous remet sa première clé. Avec cette clé, vous pouvez ensuite créer et révoquer vos propres clés, voir Clés de l'API IA.

URL de base

Toutes les requêtes sont envoyées à :

https://api.ultineo.com/v1/ai/

Seul HTTPS est servi. Une requête sur http:// reçoit une redirection 301 vers le même chemin en https://.

Important — Votre clé circule dans un en-tête de requête : une seule requête en clair la divulgue en entier. Appelez toujours directement l'adresse https:// au lieu de compter sur la redirection.

Un point d'accès ne demande aucune clé ; vous pouvez l'utiliser pour vérifier que l'hôte est joignable :

curl https://api.ultineo.com/health

{
  "code": 200,
  "title": "OK",
  "response": "api gateway"
}

Authentification

Envoyez votre clé comme jeton Bearer à chaque appel :

Une clé appartient à un seul projet IA. Toute lecture et toute écriture sont limitées à ce projet, quoi que vous mettiez dans l'URL ou le corps : un élément d'un autre projet répond exactement comme un élément qui n'existe pas.

Seule une empreinte de votre clé est conservée : une clé perdue ne peut pas être récupérée, révoquez-la et créez-en une nouvelle. Une clé peut aussi être suspendue ou porter une date d'expiration ; une clé suspendue, révoquée ou expirée est refusée (voir Codes d'erreur de l'API IA).

Remarque — L'API IA et l'API boutique décrite dans Votre premier appel partagent l'hôte api.ultineo.com mais pas leurs clés. Une clé de boutique est refusée sur tous les chemins /v1/ai/, et une clé de projet IA est refusée sur les chemins de la boutique.

Points d'accès

Chaque chemin a la forme /v1/ai/<ressource>/<action>. Une action qui porte sur un seul élément prend son identifiant comme dernier segment du chemin, par exemple /v1/ai/run/detail/runi_….

Chaque identifiant est une chaîne opaque préfixée — mapp_ pour une application, runi_ pour une exécution, papi_ pour une clé — à traiter comme une valeur opaque, sans l'analyser. Tout autre chemin répond 404.

Droits

Une clé porte une liste de droits, et chaque point d'accès en exige un. La grammaire a trois formes :

La lecture demande l'action :read, la création et la modification demandent :write. Appelez GET /v1/ai/key/detail/current pour voir les droits de votre clé (voir Clés de l'API IA). Un appel auquel il manque son droit est refusé avec 403 et un message qui nomme le droit manquant.

Remarque — Les points d'accès des exécutions utilisent les droits reasoning, pas run : une clé limitée à run:* ne peut ni lancer ni lire d'exécution.

Faire l'appel

Cet appel lance une exécution de l'une de vos applications :

curl -X POST https://api.ultineo.com/v1/ai/run/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "mapp_0ceacb46e5b3a99e91b6",
    "data": { "message": "My parcel has not arrived and the tracking has not moved for a week." }
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "runi_1b7f4e0c96a2d8531fca",
    "object": "reasoning",
    "data": { "message": "My parcel has not arrived and the tracking has not moved for a week." },
    "instruction": { "1": "Classify the message as low, normal or urgent." },
    "status": "new",
    "created_at": 1789210200
  }
}

Les exécutions sont asynchrones. Relisez l'exécution avec son id jusqu'à ce que son statut soit finished ou failed :

curl https://api.ultineo.com/v1/ai/run/detail/runi_1b7f4e0c96a2d8531fca \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

Une exécution terminée porte la réponse du modèle dans response, avec sa durée et ses nombres de jetons. Voir Exécutions IA.

L'enveloppe de réponse

Chaque point d'accès répond avec les trois mêmes clés, en cas de succès comme d'échec. Lisez d'abord le code de statut HTTP, puis response.

Un élément unique est placé directement dans response, avec un champ object qui nomme son type. Une liste enveloppe ses lignes :

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "data": [],
    "total": 0
  }
}

total compte toutes les lignes qui correspondent, et non le nombre renvoyé dans data : utilisez-le pour paginer.

Pagination

Les points d'accès list acceptent deux paramètres de requête :

Les lignes arrivent de la plus récente à la plus ancienne.

Dates et valeurs vides

Chaque horodatage est un nombre entier de secondes depuis l'epoch Unix, en UTC. Un horodatage qui n'a pas encore eu lieu vaut null et non 0 : ainsi "expires_at": null signifie que la clé n'expire jamais. Un champ texte jamais rempli est une chaîne vide et non null.

Corps de requête

Envoyez les corps POST et PATCH sous forme d'objet JSON avec Content-Type: application/json. Un corps qui n'est pas du JSON valide, ou qui n'est pas un objet JSON, est refusé avec 400 et le message Invalid JSON. Un corps de plus de 200 000 octets est refusé avec 413.

Un PATCH ne modifie que les champs que vous envoyez. N'envoyer aucun champ reconnu est une erreur et non un succès silencieux : un 200 signifie que votre modification a été appliquée.