ULTINEO

Exécutions IA

Une exécution fait tourner une application : vous fournissez les champs d'entrée de l'application, l'API met le travail en file d'attente et la réponse est rédigée. Les exécutions sont asynchrones : en créer une répond aussitôt avec le statut new, et vous relisez le résultat une fois l'exécution terminée.

Points d'accès

MéthodeCheminDroit
POST/v1/ai/run/createreasoning:write
GET/v1/ai/run/listreasoning:read
GET/v1/ai/run/detail/<run_id>reasoning:read

<run_id> est un identifiant d'exécution, préfixé runi_.

Remarque — Le segment de chemin est run, mais les droits sont reasoning:read et reasoning:write, et l'objet est un reasoning. Une clé limitée à run:* ne peut pas appeler ces points d'accès. Utilisez reasoning:*, ou *.

L'objet reasoning

ChampTypeDescription
idchaîneL'identifiant de l'exécution, préfixé runi_.
objectchaîneToujours reasoning.
app_idchaîneL'application exécutée.
dataobjetLes entrées avec lesquelles l'exécution a été lancée, par nom de champ.
instructionobjetLes instructions envoyées, par identifiant d'instruction.
responseobjetLa réponse, par identifiant d'instruction. Vide tant que l'exécution n'est pas terminée.
tokensobjetLes nombres de jetons input, output et total, ou null s'ils ne sont pas mesurés.
statuschaîneVoir les statuts ci-dessous.
durationnombreLa durée de l'exécution, en secondes à deux décimales, ou null.
started_atentierLe moment où l'exécution a été prise en charge, ou null.
finished_atentierLe moment où l'exécution s'est terminée, ou null.
created_atentierLe moment de la mise en file d'attente, en secondes Unix.
updated_atentierDernière modification, en secondes Unix.

Statuts

StatutSignification
newEn file d'attente, pas encore prise en charge.
pullEn préparation.
processingEn cours d'exécution.
finishedTerminée. response est rempli.
failedTerminée sur une erreur.

Interrogez GET /v1/ai/run/detail/<run_id> jusqu'à ce que le statut soit finished ou failed. Ces deux statuts sont définitifs ; tous les autres évoluent d'eux-mêmes.

Lancer une exécution

POST /v1/ai/run/create désigne une application et fournit ses entrées.

ParamètreTypeObligatoireDescription
app_idchaîneOuiL'application à exécuter. Accepté aussi sous app ou app_ident.
dataobjetOuiUne entrée par champ d'entrée, indexée par le name du champ tel que le renvoie Applications IA.
curl
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." }
  }'
application/json
{
  "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
  }
}

Gardez l'id renvoyé et interrogez-le. La réponse de création ne contient pas de champ response : rien n'a encore été exécuté.

Vous pouvez exécuter vos propres applications, ainsi que toute application publique activée d'un autre projet dont vous connaissez l'identifiant. Une application non activée ou privée à un autre projet est refusée avec 422 et le message général.

CodeMessageCause
400Missing required field: app_id.Aucune application n'a été désignée.
404App not found.L'application n'existe pas ou a été supprimée.
422Missing required field: <name>.Un champ d'entrée obligatoire était absent ou vide.
422The parameter '<key>' is not recognized.data contient une clé qui n'est pas un champ de l'application.

Une exécution n'est jamais refusée pour cause de consommation : les exécutions sont tarifées au jeton. Lisez le montant de la semaine dans Consommation de jetons IA et tarif.

Astuce — Un champ peut aussi être indexé par son identifiant madi_ ou par sa position, à partir de 1. L'indexation par name est la plus claire, et c'est celle que donne le schéma de l'application.

Envoyer un document ou une image

Un champ de type document ou image (voir Applications IA) ne prend pas de texte : il prend un fichier déjà présent dans la bibliothèque de fichiers de votre projet. Envoyez l'identifiant du fichier, préfixé file_, ou son URL de diffusion. L'API ne téléverse pas de fichiers elle-même.

CodeMessageCause
422Field '<name>' expects an uploaded file: send its cdn file id (file_<20 hex>) or its delivery URL.La valeur était un texte ordinaire.
422This project has no CDN scope, so no file can be attached to a reasoning.Votre projet n'a pas de bibliothèque de fichiers.
422The file sent for '<name>' is not in this project's reasoning image library.Le fichier appartient à un autre projet, a été supprimé ou se trouve dans une autre bibliothèque. Le message indique reasoning document library pour un champ document.
422The file sent for '<name>' cannot be read: accepted document formats are pdf, docx, xlsx, csv, txt.Le document est dans un format qui ne peut pas être lu.
422This application cannot read images.L'application a un champ image et les images ne peuvent pas être lues pour le moment.

Lancer plusieurs exécutions à la fois

Envoyez une liste runs au lieu d'une exécution unique pour mettre jusqu'à 100 exécutions en file d'attente en un seul appel. Chaque élément a la même forme qu'une exécution unique.

curl
curl -X POST https://api.ultineo.com/v1/ai/run/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "runs": [
      { "app_id": "mapp_0ceacb46e5b3a99e91b6", "data": { "message": "Where is my order?" } },
      { "app_id": "mapp_0ceacb46e5b3a99e91b6", "data": {} }
    ]
  }'
application/json
{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "data": [
      {
        "id": "runi_8d20c5e4a91f7b3a6c05",
        "object": "reasoning",
        "data": { "message": "Where is my order?" },
        "instruction": { "1": "Classify the message as low, normal or urgent." },
        "status": "new",
        "created_at": 1789210260
      }
    ],
    "created": 1,
    "failed": 1,
    "errors": [
      {
        "index": 1,
        "code": 422,
        "title": "Unprocessable entity",
        "response": "Missing required field: message."
      }
    ],
    "total": 2
  }
}

Un élément refusé ne bloque jamais les autres : chaque refus est indiqué dans errors avec sa position dans votre liste runs, à partir de 0. L'appel répond 200 dès qu'une exécution a été mise en file d'attente, et 422 seulement quand tous les éléments ont été refusés. Une valeur runs qui n'est pas une liste, qui est vide ou qui contient plus de 100 éléments est refusée en bloc avec 422.

Lire une exécution

GET /v1/ai/run/detail/<run_id> renvoie l'exécution complète, y compris la réponse dès qu'elle existe.

curl
curl https://api.ultineo.com/v1/ai/run/detail/runi_1b7f4e0c96a2d8531fca \
  -H "Authorization: Bearer sk-project-YOUR_KEY"
application/json
{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "runi_1b7f4e0c96a2d8531fca",
    "object": "reasoning",
    "app_id": "mapp_0ceacb46e5b3a99e91b6",
    "data": { "message": "My parcel has not arrived and the tracking has not moved for a week." },
    "instruction": {
      "miid_9a4c07e5b312df8641ca": "Classify the message as low, normal or urgent."
    },
    "response": {
      "miid_9a4c07e5b312df8641ca": "urgent"
    },
    "tokens": { "input": 412, "output": 3, "total": 415 },
    "status": "finished",
    "duration": 1.84,
    "started_at": 1789210202,
    "finished_at": 1789210204,
    "created_at": 1789210200,
    "updated_at": 1789210204
  }
}

instruction et response partagent leurs clés : vous pouvez associer chaque réponse à l'instruction qui l'a produite. Une exécution d'un autre projet renvoie 404 et Reasoning not found.

Lister les exécutions

GET /v1/ai/run/list renvoie les exécutions de votre projet, de la plus récente à la plus ancienne.

ParamètreTypeDescription
app_idchaîneNe renvoyer que les exécutions d'une application. Accepté aussi sous app ou app_ident.
limitentierNombre de lignes à renvoyer, de 1 à 100. 50 par défaut.
offsetentierNombre de lignes à sauter. 0 par défaut.
curl
curl "https://api.ultineo.com/v1/ai/run/list?app_id=mapp_0ceacb46e5b3a99e91b6&limit=2" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"
application/json
{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "data": [
      {
        "id": "runi_1b7f4e0c96a2d8531fca",
        "object": "reasoning",
        "app_id": "mapp_0ceacb46e5b3a99e91b6",
        "status": "finished",
        "duration": 1.84,
        "started_at": 1789210202,
        "finished_at": 1789210204,
        "created_at": 1789210200,
        "updated_at": 1789210204,
        "tokens": { "input": 412, "output": 3, "total": 415 }
      }
    ],
    "total": 1
  }
}

La liste omet data, instruction et response : lisez une exécution pour les obtenir. Lister ne consomme aucun jeton, vous pouvez donc consulter l'historique librement.