API Images d'AICU

Alpha. Une clé, un endpoint — passez de GPT-Image-2 à Nano Banana 2 (Gemini) en changeant un seul paramètre.

Voir ce qu'elle fait avant de lire la référence

Tout ce qui suit est la référence. Si vous préférez d'abord la voir fonctionner, ces trois images ont chacune été obtenues en une seule requête, avec le curl de cette page.

Six personnages nommés dans une seule image, chacun conservant son propre design. Le plus difficile n'est pas de dessiner six personnes, mais d'éviter qu'elles se confondent les unes avec les autres.

Une bande dessinée en quatre cases en une seule requête. Le même personnage dans les quatre, avec des cases mises en page par le modèle plutôt qu'assemblées après coup.

Une planche de sprites en neuf poses sur fond uni, prête à être découpée pour un jeu ou un rig de VTuber.

Les guides pas à pas

Ils sont écrits pour être lus, pas consultés — commencez ici si la référence ci-dessous vous paraît ardue.

	Ce qu'il montre
GPT-Image-2.5 — le manuel de l'API, traduit	Chaque paramètre, en japonais, avec ce que chacun change réellement
Le guide de prompting, traduit	Comment écrire des prompts spécifiquement pour ce modèle, avec un exemple de génération par lots
Guide de génération d'images, partie 1	Choisir une API, édition en plusieurs tours, streaming
L'essai sur nos propres personnages	Les trois images ci-dessus, avec les prompts exacts qui les ont produites
AiCutyBench — reproduit-il vraiment un personnage ?	Taux de réussite mesuré sur des exécutions répétées, pas une démo triée sur le volet

URL de base

https://api.aicu.ai/v1

Authentification

Vous avez besoin d'une clé API avec le scope images. Émettez-en une depuis le tableau de bord.

Authorization: Bearer aicu_live_xxx

GET /v1/images/models

Les modèles d'images à votre disposition (aucune authentification requise).

curl https://api.aicu.ai/v1/images/models

model	Fournisseur	Image de référence	Format d'image	Remarques
gpt-image-2	OpenAI	○	-	Haute qualité, forte cohérence des personnages
nano-banana	Gemini	○	○	Rapide, prend en charge les formats d'image
sd3.5-large	Stability	-	-	Stable Diffusion 3.5 Large

Les noms de modèles du service que vous quittez (gemini-3.1-flash-image-preview, par exemple) sont acceptés tels quels.

POST /v1/images/generations

curl -X POST https://api.aicu.ai/v1/images/generations \
  -H "Authorization: Bearer aicu_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "prompt": "a red apple on a white table, product photo",
    "aspect_ratio": "16:9"
  }'

Requête

Paramètre	Type	Description
prompt	string	Obligatoire. Ce qu'il faut générer
model	string	Par défaut gpt-image-2
aspect_ratio	string	16:9 et similaires (nano-banana uniquement)
size	string	1024x1024, 1536x1024, etc.
quality	string	low / medium / high
reference_image	string	Image de référence en base64 (les data URL sont acceptées)
character	string	Préréglage d'image de référence. Prioritaire sur model
seed	number	Pour une sortie reproductible (sd3.5-large)
force	boolean	true contourne le cache et régénère

Réponse

Elle est renvoyée au format compatible OpenAI.

{
  "id": "0f3c9a52-…",
  "data": [{
    "b64_json": "iVBORw0KG...",
    "url": "https://api.aicu.ai/v1/images/file/0f3c9a52-…"
  }],
  "cached": false,
  "ap_cost": 1170
}

Une régénération avec des entrées identiques est servie depuis le cache R2, et les réponses en cache sont gratuites (cached: true). ap_cost est le montant facturé pour cet appel (le nombre ci-dessus n'est qu'un exemple — les prix actuels figurent sur la page des modèles).

Afficher l'image dans un navigateur

Chaque réponse de génération contient l'image deux fois : intégrée sous forme de b64_json, et sous forme d'une url qui pointe vers le fichier stocké.

L'url nécessite votre clé API. GET /v1/images/file/{id} renvoie 401 sans en-tête Authorization ; elle ne fonctionne donc pas comme <img src> — un navigateur n'envoie aucune clé, et vous ne devez jamais transmettre votre clé à un navigateur.

Pour une page web ou un widget, utilisez l'une de ces méthodes :

• Utilisez directement b64_json. <img src="data:image/png;base64,…"> fonctionne tel quel. Convient pour afficher l'image que vous venez de générer.
• Récupérez le fichier sur votre serveur et servez-le à nouveau. Votre backend appelle GET /v1/images/file/{id} avec la clé et renvoie les octets (ou les stocke dans votre propre bucket). C'est la bonne approche pour les galeries : conservez l'id, pas le base64.

GET /v1/images/recent liste vos images avec un id et une url, mais sans données d'image intégrées — récupérez chaque fichier avec la clé de la même façon.

⏱ Les générations de plus de 60 secondes sont livrées par e-mail

Certaines générations prennent plus de 60 secondes — réglages de haute qualité (xhigh / max), requêtes avec une image de référence, grandes tailles, et gpt-image-2 (mesuré entre 113 et 171 secondes).

Elles ne sont pas faites pour être attendues à l'intérieur d'une application. La plupart des clients HTTP abandonnent après 30 à 60 secondes, et la périphérie (edge) de Cloudflare coupe la connexion à 100 secondes. Quand cela arrive, cela ressemble à un échec, mais la génération se termine de notre côté et vous n'êtes facturé qu'une seule fois. Ne relancez pas parce que la requête a expiré — chaque nouvel essai gaspille quelques milliers d'AP.

Le résultat d'une génération qui dépasse 60 secondes est livré par e-mail, avec l'image en pièce jointe, au propriétaire de la clé (et à notify_email si vous l'avez défini). Vous pouvez refuser avec "notify_on_timeout": false — mais vous aurez alors un moyen de moins de recevoir le résultat.

Autres moyens de récupérer l'image :

1. GET /v1/images/status/{id} — l'id du corps de la réponse, ou l'en-tête X-AICU-Image-Id (envoyé dès l'ouverture de la connexion en streaming). Utilisez celui-ci. Il récupère exactement la génération que vous avez demandée
2. GET /v1/images/recent — liste vos générations récentes avec leurs identifiants. ⚠️ En cas de générations simultanées sur la même clé, cela renvoie l'image de quelqu'un d'autre ; préférez status/{id}
3. L'historique d'utilisation dans le tableau de bord

Si vous développez une application qui affiche l'image immédiatement :

• Utilisez quality low / medium / high en 1024x1024. GET /v1/images/models indique typical_latency_s_by_quality, ce qui vous permet de vérifier le temps attendu avant l'appel
• Passez "stream": true — des images partielles continuent d'arriver via SSE, la connexion ne reste donc jamais inactive (incompatible avec character / reference_image / mask ; génération simple uniquement)
• Passez "notify_email" (avec "app_name") pour prévenir directement votre propre utilisateur final quand l'image est prête
• Si vous tenez vraiment à un appel synchrone, portez le délai d'attente de votre client à 240 secondes ou plus (--max-time 240 pour curl, timeout=240 pour requests)

La génération vidéo est asynchrone dès le départ : POST /v1/video/generate renvoie 202 avec un identifiant, et vous interrogez GET /v1/video/status/{id}.

Garder un personnage cohérent grâce aux images de référence

Option 1 : les préréglages de personnages enregistrés (character) — les personnages officiels AiCuty sont déjà enregistrés : vous obtenez une apparence cohérente sans préparer la moindre image de référence.

# Les lister (sans authentification) : renvoie le slug, le modèle, le tarif et les mentions de droits
curl https://api.aicu.ai/v1/images/characters

# En utiliser un : passez simplement le slug dans character (insensible à la casse)
curl -X POST https://api.aicu.ai/v1/images/generations \
  -H "Authorization: Bearer aicu_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"character": "SakiNoir", "prompt": "カフェで読書している、午後の光"}'

Préréglages enregistrés (images de référence incluses, gpt-image-2) : SakiNoir / NaoVerde / MeiSoleil / ElenaBloom / MinaAzure / elec_sheep, entre autres. Le champ rights de l'API de liste indique la mention de crédit et le titulaire des droits — respectez-le lorsque vous publiez.

Option 2 : votre propre image de référence (reference_image) — rien n'a besoin d'être téléversé sur R2 au préalable. Envoyez simplement l'image dont vous disposez en base64.

import base64, requests

ref = base64.b64encode(open("character.png", "rb").read()).decode()
res = requests.post(
    "https://api.aicu.ai/v1/images/generations",
    headers={"Authorization": "Bearer aicu_live_xxx"},
    json={
        "model": "nano-banana",
        "prompt": "Using the reference image as a character guide, draw the same character waving hello",
        "reference_image": ref,
        "aspect_ratio": "16:9",
    },
    timeout=180,
)
open("out.png", "wb").write(base64.b64decode(res.json()["data"][0]["b64_json"]))

Guide de migration : remplacer OpenAI / Gemini

Migrer depuis Gemini (google-genai)

- client = genai.Client(api_key=GEMINI_API_KEY)
- response = client.models.generate_content(
-     model="gemini-3.1-flash-image-preview",
-     contents=prompt,
-     config=types.GenerateContentConfig(
-         response_modalities=["IMAGE", "TEXT"],
-         image_config=types.ImageConfig(aspect_ratio="16:9"),
-     ),
- )
+ res = requests.post(
+     "https://api.aicu.ai/v1/images/generations",
+     headers={"Authorization": f"Bearer {AICU_API_KEY}"},
+     json={"model": "nano-banana", "prompt": prompt, "aspect_ratio": "16:9"},
+ )

Migrer depuis le SDK OpenAI

- client = OpenAI(api_key=OPENAI_API_KEY)
- res = client.images.generate(model="gpt-image-2", prompt=prompt, size="1024x1024")
+ res = requests.post(
+     "https://api.aicu.ai/v1/images/generations",
+     headers={"Authorization": f"Bearer {AICU_API_KEY}"},
+     json={"model": "gpt-image-2", "prompt": prompt, "size": "1024x1024"},
+ )

Une fois la bascule faite, vous n'avez plus de clés à gérer pour chaque fournisseur, et l'utilisation comme les coûts arrivent dans un seul tableau de bord.

Erreurs

Statut	Signification
401	Clé API invalide
403	La clé n'a pas le scope images
402	Crédits insuffisants
404	Modèle inconnu
503	Clé du fournisseur non configurée / échec de la génération

Consulter l'utilisation

curl https://api.aicu.ai/v1/usage -H "Authorization: Bearer aicu_live_xxx"

L'historique d'utilisation du tableau de bord peut être filtré pour n'afficher que les images.

Assistance

• Tableau de bord : https://api.aicu.ai/dashboard
• Contact : https://aicu.ai/contact

© 2026 AICU Inc.