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 le modèle produit la réponse. 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

<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

L'objet model nomme le modèle et sa version exacte :

Statuts

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.

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
  }
}

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, sans modèle utilisable ou privée à un autre projet est refusée avec 422 et le message général.

Le quota est vérifié avant tout le reste : un projet sans allocation restante ne peut rien mettre en file d'attente. Lisez l'allocation restante dans Quota et consommation de jetons IA.

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.

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 -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": {} }
    ]
  }'

{
  "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 https://api.ultineo.com/v1/ai/run/detail/runi_1b7f4e0c96a2d8531fca \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "runi_1b7f4e0c96a2d8531fca",
    "object": "reasoning",
    "app_id": "mapp_0ceacb46e5b3a99e91b6",
    "model": {
      "id": "modi_c2b7e9a1d3f0a8645c8e",
      "model_library": "mlyi_c2a1e7d9b4f30685c3a3",
      "name": "qwen3:4b",
      "parameter": 4
    },
    "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.

curl "https://api.ultineo.com/v1/ai/run/list?app_id=mapp_0ceacb46e5b3a99e91b6&limit=2" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "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, response et model : lisez une exécution pour les obtenir. Lister n'entame jamais votre quota, vous pouvez donc consulter l'historique librement.