Génération IA
32 routes. Chemins relatifs à https://api.nexus-engine.eu/api/v1.
GET
/generation/offre
Ce que ce serveur sait générer (Nexus Image, Vidéo, Son, 3D) : les opérations avec leur prix en crédits et son équivalent lisible, combien de fournisseurs configurés savent les faire, les tranches de crédits et le solde de la personne (le champ `socle`, gardé pour les postes plus anciens, vaut zéro).
Réponse{ compte, solde, creditCentimesHt, tranches, socle, services[], operations: [{ id, service, libelle, credits, lisible, fournisseurs, seul }] }
Note`compte` faux = ce serveur ne compte pas les crédits (lot 1 : tout est accordé). `fournisseurs: 0` = l’opération est refusée NON_REGLE ici. Le nom des fournisseurs n’est pas rendu : c’est un détail de la carte d’une génération.
GET
/generation/etat
Ce qui est OUVERT maintenant : chaque opération jugée comme le moteur la jugerait (clé de fournisseur, garde du prix, réserve prépayée, compte du fournisseur sondé), avec la phrase qui dit pourquoi elle est fermée, les services, et le solde de la personne. Aucun projet requis.
Réponse{ compte, solde, rechargeOuverte, ouvert, services: [{ id, libelle, ouvert, ouvertes, total }], operations: [{ id, service, libelle, credits, lisible, ouverte, code, raison }], source: "serveur" }
Note`code` d’une opération fermée : NON_REGLE (aucune clé), PRIX, RESERVE, COMPTE (le compte de Nexus chez le fournisseur est à sec : ce n’est pas le solde de la personne), PANNE (passagère). Le prix est celui des réglages par défaut : l’estimation d’une demande précise fait foi.
POST
/projects/:id/generations/estimation
Le prix AVANT le clic : crédits, équivalent lisible (« 25 crédits · environ 5 secondes de vidéo »), solde de la personne et « de quoi en faire N ».
CorpsLa même demande que POST /projects/:id/generations
RéponseEstimationDto { operation, credits, lisible, solde, fois, fournisseurs, pilotes (nom, modèle, disponible), choisi }
NoteFermé à une clé et à un agent sur un projet en mode aveugle. Une demande incomplète pour son opération répond 400 `ENTREE_INVALIDE` en nommant ce qui manque.
POST
/projects/:id/generations
Générer : une image, une retouche, un agrandissement, une vidéo (depuis un texte ou une image), une musique, un bruitage, une voix, une transcription, un modèle 3D (depuis un texte ou une image), une texture, un rig, une animation. Un seul mot : le service et le fournisseur se déduisent de l’opération ; le résultat arrive dans le Studio du projet.
Corpsoperation (image.generer, image.retoucher, image.agrandir, video.depuis-texte, video.depuis-image, video.depuis-video, son.musique, son.bruitage, son.voix, son.transcrire, 3d.depuis-texte, 3d.depuis-image, 3d.texturer, 3d.rigger, 3d.animer), prompt?, entrees? [{ role (image, masque, video, son, modele, reference), source: creation { creationId, version? } | url { url https } | octets { type, base64 } }], options? { qualite (brouillon, finale), gamme (rapide, standard, premium), dureeS, dureeMs, ratio, graine, langue, voix, instrumental, format3d, animations[], squelette, hauteurM }, destination? { creationId (une version de plus) | dossier, titre, nomFichier | clipId | assetId }, idempotence?, contexte? { discussionId, tacheId, origine }
RéponseGenerationDto — 202 lancée ou EN_ATTENTE_RESERVE, 201 déjà réussie (fournisseur synchrone), 200 déjà connue (même `idempotence`)
NoteLes crédits sont RÉSERVÉS au lancement, DÉBITÉS à la réussite, RENDUS à l’échec (D18) : un refus (`refus`, `raison`) n’a rien débité. 402 SOLDE_INSUFFISANT ou PLAFOND_PROJET, 403 MODE_AVEUGLE ou POLITIQUE, 400 ENTREE_INVALIDE, 413 TROP_LOURD, 422 CONTENU_REFUSE, 503 NON_REGLE, FOURNISSEUR_INDISPONIBLE ou RESERVE_FOURNISSEUR. Une panne chez un fournisseur fait passer au suivant ; un refus de contenu, jamais. Le résultat (`resultat.creationId`, `version`) est une création ou une version du Studio, annoncée aux postes.
GET
/projects/:id/generations
Les générations d’un projet, les plus récentes d’abord, avec leur état, leur coût et où le résultat est allé.
Requêteetat (ESTIMEE, EN_ATTENTE_RESERVE, LANCEE, EN_COURS, REUSSIE, ECHOUEE, ANNULEE, INCONNUE), service (image, video, son, 3d), offset, limit (≤ 100)
Réponse{ total, items: GenerationDto[] }
NoteFermé à une clé et à un agent sur un projet en mode aveugle.
GET
/generations/:id
Une génération : état, fournisseur et modèle (le détail), crédits estimés et débités, résultat, refus, recette rejouable.
RéponseGenerationDto
NoteUne génération d’une autre entreprise est introuvable (404). Fermé à une clé et à un agent sur un projet en mode aveugle.
POST
/projects/:id/generations/locale
Ranger une génération faite SUR LE POSTE par un pilote local (ComfyUI, Automatic1111, Whisper, Real-ESRGAN) : le fichier va au Studio du projet, la ligne dit « sur votre machine, 0 crédit ».
Corpsoperation, pilote, prompt?, fichier { nom, type, base64 }, destination?, contexte?
RéponseGenerationDto (fournisseur `local`, 0 crédit)
NoteRien n’a quitté le poste : pas de garde du mode aveugle. Corps jusqu’à 56 Mo. Journal `generation.route`.
GET
/projects/:id/generations/registre
Le registre des licences du projet : une ligne par génération réussie (service, modèle, date, licence), en Markdown — la pièce qu’on joint à un dossier client.
Requêteformat (markdown, md, json)
Réponsetext/markdown en pièce jointe ; `json` : { registre, markdown }
NoteUn autre format répond 406 `FORMAT` : le serveur ne compose pas de PDF. Fermé à une clé et à un agent sur un projet en mode aveugle.
POST
/generations/:id/annuler
Annuler une génération qui n’est pas finie : le fournisseur est prévenu quand il le permet, les crédits réservés sont rendus.
RéponseGenerationDto (ANNULEE, ou telle quelle si elle était déjà finie)
GET
/me/runners/offre
Ce que les terminaux sur le serveur de Nexus me coûtent : quota du mois, solde, prix par gabarit, et si le service est ouvert.
GET
/me/runners
Mes terminaux sur le serveur, les derniers en premier.
POST
/me/runners
session de l’application seulement
Lancer un terminal sur le serveur de Nexus : le quota du mois d’abord, les crédits seulement avec l’accord.
Corpsservice, projectId, consigne, engine, modele, accepteCredits
RéponseRunnerDto
NoteLe geste d’une personne : une clé et un agent sont refusés. Refus en code : FERME, QUOTA_EPUISE, SOLDE_INSUFFISANT, TROP_DE_RUNNERS, MACHINE_PLEINE, PROJET_AVEUGLE, SERVICE_SUR_POSTE_SEUL, DEMARRAGE_IMPOSSIBLE.
POST
/me/runners/:id/arreter
Arrêter un de mes terminaux. Seules les minutes passées sont débitées.
POST
/runners/hote/annonce
sans authentification
L’hôte d’un terminal sur le serveur s’annonce comme un poste.
Réponse{ ok }
NoteRéservée à la machine d’exécution d’un terminal, authentifiée par le JETON de l’hôte en porteur (`Authorization: Bearer`), qui meurt avec le terminal. Pas une API pour les agences.
GET
/runners/hote/mission
sans authentification
Ce que l’hôte d’un terminal doit lancer : projet, moteur, consigne et dépôt.
Réponse{ runnerId, deviceId, projectId, projetNom, engine, modele, consigne, depot }
NoteRéservée à la machine d’exécution d’un terminal, authentifiée par le jeton de l’hôte en porteur, qui meurt avec le terminal. Pas une API pour les agences.
POST
/runners/hote/fin
sans authentification
L’hôte signale que son terminal a fini, ou n’a pas pu partir.
Réponse{ ok }
NoteRéservée à la machine d’exécution d’un terminal, authentifiée par le jeton de l’hôte en porteur, qui meurt avec le terminal. Pas une API pour les agences.
POST
/runners/hote/reponse
sans authentification
L’hôte d’un terminal rend le résultat d’un ordre.
Réponse{ ok }
NoteRéservée à la machine d’exécution d’un terminal, authentifiée par le JETON de l’hôte en porteur (`Authorization: Bearer`), qui meurt avec le terminal. Pas une API pour les agences.
GET
/runners/hote/flux
sans authentification
Le flux des ordres destinés à l’hôte d’un terminal (SSE).
Réponsetext/event-stream
NoteRéservée à la machine d’exécution d’un terminal, authentifiée par le JETON de l’hôte en porteur (`Authorization: Bearer`), qui meurt avec le terminal. Pas une API pour les agences.
GET
/me/credits
Mes crédits Nexus : le solde dépensable (les crédits achetés par l’espace), ce qui est disponible et réservé, les tranches à acheter (HT, TTC, équivalents lisibles), les derniers achats et mouvements.
RéponseCreditsDto { compte, solde, socle { mois, credits, consommes, reserves, restants, renouvellementLe, origine }, packs { disponibles, reserves, achetesTotal, consommesTotal }, achatPossible, achatRefus, paiementConfigure, creditCentimesHt, tvaTauxPourcent, tranches[], achats[], mouvements[], recusTotal? }
NoteLes crédits achetés sont à l’ESPACE et se partagent entre ses membres. Aucune licence n’inclut de crédits depuis le 6 novembre 2026 : le champ `socle` reste dans la réponse pour les postes plus anciens et vaut zéro — ne pas le montrer. `compte` faux = ce serveur ne compte pas.
GET
/me/credits/mouvements
L’historique des mouvements de crédits de l’espace (recharges, générations, remboursements), page par page, filtré par période ; le total et les mois qui en portent.
Requêtepage (défaut 1), taille (1-100, défaut 20), periode (AAAA ou AAAA-MM, UTC) — ou, forme à curseur d’avant : avant (ISO), limite (1-200, défaut 50)
Réponse{ mouvements: MouvementCreditsDto[], total, page, taille, pages, periode, periodes: { mois, nombre }[] } ; avec avant/limite : { mouvements, suite: ISO | null }
NoteSans `avant` ni `limite`, c’est la page (même règle que les reçus). Une page au-delà de la dernière rend la dernière.
GET
/me/credits/achats
Les recharges de crédits de l’espace et leurs reçus, page par page, filtrées par période ; le total et les mois qui en portent.
Requêtepage (défaut 1), taille (1-100, défaut 20), periode (AAAA ou AAAA-MM, UTC)
Réponse{ achats: AchatCreditsDto[], total, page, taille, pages, periode, periodes: { mois, nombre }[] }
NoteLu dans la base de Nexus : Stripe n’est jamais appelé pour lister. Une page au-delà de la dernière rend la dernière.
POST
/me/credits/recharger
session de l’application seulement
Acheter une tranche de crédits : ouvre la page de paiement Stripe et rend son adresse. Les crédits arrivent à la notification de l’encaissement, jamais au retour de la page.
Corpstranche (index dans les tranches de GET /me/credits)
Réponse{ url }
NoteLe geste d’une personne devant son écran : une clé et un agent sont refusés. 402 sans licence servie (l’offre gratuite et l’essai n’achètent pas), 503 sans Stripe configuré.
GET
/credits/plafonds
Les plafonds mensuels de crédits des projets de l’espace, et ce que chacun a engagé ce mois-ci (réservé ou débité, hors échecs et annulations).
Réponse{ projets: PlafondProjetDto[] { projectId, name, color, plafond | null, engages } }
NoteAdministrateur. La somme engagée est celle que le moteur compare au plafond avant de refuser PLAFOND_PROJET.
PUT
/projects/:id/generation-plafond
session de l’application seulement
Poser ou ôter (null) le plafond mensuel de crédits d’un projet (D6).
Corpscredits (entier ≥ 0, ou null)
RéponsePlafondProjetDto
NoteAdministrateur, devant son écran : une clé et un agent sont refusés. 404 pour un projet d’un autre espace.
GET
/credits/plafonds-membres
Owner et Admin
Les plafonds mensuels de génération des personnes de l’espace — le leur, et l’enveloppe de leurs agents —, avec ce que chacune a engagé ce mois-ci dans la portée de sa ligne.
Réponse{ lignes: PlafondMembreDto[] { memberId, name, projectId | null, projectName, credits | null, creditsAgent | null, engages, engagesAgent }, membres: { id, name }[] }
NoteAdministrateur. L’engagé se compte comme le moteur le compare : réservé ou débité, hors échecs et annulations, depuis le premier jour du mois civil (UTC). Une ligne d’un projet supprimé n’est pas rendue.
PUT
/members/:id/generation-plafond
Owner et Admin session de l’application seulement
Poser, changer ou ôter le plafond mensuel de génération d’une personne, et l’enveloppe accordée d’avance à ses agents.
Corpscredits (entier ≥ 0, ou null) ; creditsAgent? (entier ≥ 0, ou null) ; projectId? (un projet ; absent ou null : tous ses projets)
RéponsePlafondsMembresDto
NoteAdministrateur, devant son écran : un agent ne relève pas sa propre enveloppe, une clé non plus. Les deux nombres nuls ôtent la ligne. 404, sans dire lequel, pour une personne ou un projet d’un autre espace. Journal `credits.plafond-membre`.
POST
/projects/:id/generations/variantes
Lancer la même demande de génération de deux à quatre fois, chaque variante comptée, à choisir ensuite.
Corpsdemande: DemandeGeneration ; nombre: 2 à 4
Réponse202 VariantesGenerationDto { groupe, credits (le total), items: GenerationDto[], refus: { code, raison } | null }
NoteLe TOTAL est jugé avant la première : plafonds (projet, personne, agents — 402 PLAFOND_PROJET ou PLAFOND_MEMBRE) et solde (402 SOLDE_INSUFFISANT) ; rien n’est lancé si l’un refuse. Chaque variante est ensuite une génération ordinaire : réservée, débitée ou rendue pour elle-même, idempotence `<clé>#v<rang>`. Mode aveugle : fermé aux agents et aux clés. Journal `generation.variantes`.
GET
/projects/:id/generations/historique
L’historique des générations : d’une création (celles qui l’ont produite, qui la visaient — échecs compris —, qui sont parties d’elle), d’un groupe de variantes, ou du projet ; cherchable dans les prompts.
RequêtecreationId? ; q? (dans les prompts, sans casse) ; groupe? ; etat? ; offset ; limit (1 à 100, défaut 30)
RéponseHistoriqueGenerationsDto { total, items: (GenerationDto & { role: resultat | destination | entree | null, relance: { possible, raison } })[] }
NoteLes plus récentes d’abord ; un groupe se lit dans l’ordre de ses variantes. Mode aveugle : fermé aux agents et aux clés.
POST
/generations/:id/relancer
Relancer une génération ÉCHOUÉE ou ANNULÉE : une génération neuve, la même demande, liée à la première (`relanceDe`) et comptée comme toute génération.
Réponse202 lancée · 201 déjà réussie · 200 déjà relancée (la même) · GenerationDto
NoteDeux appels rendent la même génération neuve (idempotence `relance:<id>`) ; une relance elle-même échouée se relance au bout de la chaîne. 409, avec la raison, pour une génération réussie, en cours, faite sur la machine ou partie d’un fichier joint. Mêmes plafonds et même solde qu’une génération neuve. Journal `generation.relance`.
POST
/me/relais/jetons
session de l’application seulement
Demander un jeton de relais pour une discussion en mode crédits (D24) : le binaire le présente au relais à la place d’une clé.
Corpsmoteur (claude | codex | gemini | mistral | grok | deepseek) ou modele ; discussionId (facultatif, la ligne d’agence)
RéponseJetonRelaisCreeDto — le jeton n’est rendu qu’ici, jamais relu
NoteLe geste d’une personne (`ROUTES_SESSION_SEULE`) : payer ses tours en crédits ne se délègue ni à une clé ni à un agent. 400 pour un moteur sans relais ou un modèle hors grille ; 503 quand ce serveur n’a pas de clé chez ce fournisseur (`NEXUS_RELAIS_<FOURNISSEUR>_KEY`). Le jeton vit 24 h au plus, meurt à la révocation (la discussion refermée). Journal `relais.jeton-cree`.
GET
/me/relais/jetons/:id
Les totaux d’un jeton de relais : requêtes, jetons d’entrée, de sortie, relus du cache, crédits débités.
RéponseReleveRelaisDto
NoteDes sommes, jamais un contenu. 404 pour un jeton d’un autre membre (indiscernable d’un inexistant).
DELETE
/me/relais/jetons/:id
Révoquer un jeton de relais : la discussion est refermée, ou la personne le demande. Idempotent.
Réponse{ ok: true }
NoteJournal `relais.jeton-revoque`. 404 pour un jeton d’un autre membre.