Agent de sprites

Ce que ça fait

Un prompt devient un plan. Un graphe des outils à asset unique (générer, pivoter, animer, restyle, normal map) qui forment ensemble un pack cohérent, chaque asset accordé au style du même sprite d'ancrage. Le plan est chiffré étape par étape avant toute exécution, et rien n'est facturé tant que vous ne l'approuvez pas. Chaque asset revient avec un id et une URL de téléchargement, exactement comme les endpoints à asset unique.

Comment un pack est chiffré

Un chevalier qui marche dans quatre directions, c'est un ancrage, une rotation et quatre cycles de marche, environ 69 jetons. Demandez le but, pas les étapes. Nommez les mouvements et les directions dont le jeu a besoin, et le planificateur choisit les outils, les tailles et l'ordre.

POST/api/agent

Planifie un pack et le chiffre. Ne dépense rien. Renvoie le plan comme une exécution en awaiting_approval avec le détail par étape. L'approbation est un appel séparé.

curl https://www.sprite-ai.art/api/agent \
-H "Authorization: Bearer sai_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "prompt": "an isometric knight for a 4-direction top-down game, walking", "cap": 100 }'

const res = await fetch("https://www.sprite-ai.art/api/agent", {
method: "POST",
headers: {
  Authorization: "Bearer sai_sk_your_key_here",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  prompt: "an isometric knight for a 4-direction top-down game, walking",
  cap: 100,
}),
});
const plan = await res.json(); // plan.estimated_tokens, plan.steps

import requests

plan = requests.post(
  "https://www.sprite-ai.art/api/agent",
  headers={"Authorization": "Bearer sai_sk_your_key_here"},
  json={"prompt": "an isometric knight for a 4-direction top-down game, walking", "cap": 100},
).json()
print(plan["estimated_tokens"], [s["tool"] for s in plan["steps"]])

{
"id": "5f0e2c1a-...",
"status": "awaiting_approval",
"created_at": "2026-09-06T12:00:00.000Z",
"prompt": "an isometric knight for a 4-direction top-down game, walking",
"plan": { "version": 1, "goal": "...", "anchor_step": "s1", "steps": [ ... ] },
"steps": [
  { "key": "s1", "tool": "sprite_generate", "produces": "still", "depends_on": [], "params": { ... }, "estimated_tokens": 1 },
  { "key": "s2", "tool": "sprite_rotate", "produces": "sheet", "depends_on": ["s1"], "params": { ... }, "estimated_tokens": 12 },
  { "key": "s3", "tool": "sprite_generate_animation", "produces": "animation", "depends_on": ["s2"], "params": { ... }, "estimated_tokens": 14 }
],
"estimated_tokens": 69,
"balance": 250,
"plan_attempts": 1
}

Un plan hors budget reste un 201. Le plan est bon, c'est le solde qui manque, alors le corps porte shortfall: { cost, balance, missing } et l'exécution attend. Un prompt que le planificateur n'a pas pu transformer en plan valide donne un 422 avec code: "plan_failed" et les problèmes rencontrés. Rien n'est conservé. Un plan chiffré au-dessus de cap donne un 422 avec le coût. Montez le plafond et rappelez.

POST/api/agent/{id}/run

Approuve le plan et le lance. C'est le seul appel qui dépense. À partir d'ici, chaque étape est facturée à mesure qu'elle se termine. Renvoie 202 tout de suite. L'exécution continue sur le serveur pendant des minutes et vous l'interrogez.

curl -X POST https://www.sprite-ai.art/api/agent/5f0e2c1a-.../run \
-H "Authorization: Bearer sai_sk_your_key_here"

const res = await fetch(
"https://www.sprite-ai.art/api/agent/5f0e2c1a-.../run",
{ method: "POST", headers: { Authorization: "Bearer sai_sk_your_key_here" } },
);
const { poll_url } = await res.json();

import requests

accepted = requests.post(
  "https://www.sprite-ai.art/api/agent/5f0e2c1a-.../run",
  headers={"Authorization": "Bearer sai_sk_your_key_here"},
).json()
poll_url = accepted["poll_url"]

{
"id": "5f0e2c1a-...",
"status": "accepted",
"estimated_tokens": 69,
"poll_url": "https://www.sprite-ai.art/api/agent/5f0e2c1a-..."
}

Une exécution qui n'est pas en awaiting_approval répond 400 avec code: "run_not_approvable". Un solde passé sous le devis depuis la planification répond 402.

GET/api/agent/{id}

L'exécution et l'état de chaque étape, dérivés des lignes de génération qu'elle a produites. Interrogez-le toutes les deux secondes environ tant que status est running. Cet appel ne touche aucun fournisseur et ne dépense rien.

{
"id": "5f0e2c1a-...",
"status": "running",
"prompt": "...",
"goal": "...",
"estimated_tokens": 69,
"tokens_spent": 13,
"counts": { "total": 6, "pending": 2, "running": 2, "completed": 2, "failed": 0, "skipped": 0 },
"steps": [
  { "key": "s1", "tool": "sprite_generate", "status": "completed", "progress": 100,
    "generation_id": "a1b2c3d4-...", "download_url": "https://www.sprite-ai.art/api/sprites/a1b2c3d4-.../download",
    "tokens_spent": 1, "error": null, "is_output": false },
  { "key": "s3", "tool": "sprite_generate_animation", "status": "running", "progress": 40,
    "generation_id": "b2c3d4e5-...", "download_url": null, "tokens_spent": 0, "error": null, "is_output": true }
],
"outputs": [
  { "step_key": "s2", "generation_id": "c3d4e5f6-...", "download_url": "https://www.sprite-ai.art/api/sprites/c3d4e5f6-.../download" }
]
}

status finit en completed, failed ou cancelled. outputs liste les livrables dans l'ordre du plan. Chaque étape terminée, livrable ou non, porte sa propre download_url. Une étape dont l'entrée a échoué se lit skipped et n'est jamais facturée.

POST/api/agent/{id}/cancel

Arrête une exécution. Les étapes déjà terminées sont conservées et restent facturées. Les étapes en cours ou pas encore lancées ne sont pas facturées. Annuler un plan jamais approuvé l'abandonne.

{ "id": "5f0e2c1a-...", "status": "cancelled" }