
Ce guide de l’Ideogram 4.6 API vous mène d’une clé API à une image terminée en cURL et en Python, puis couvre chaque mode d’entrée accepté par le schéma PoYo : text-to-image en taille prédéfinie ou personnalisée, arrière-plans transparents, éditions classiques, éditions masquées, images de référence et éditions haute précision. Le text-to-image utilise l’ID de modèle ideogram-v4.6 et l’édition utilise ideogram-v4.6-edit ; les deux figurent sur la page du modèle Ideogram 4.6.
Les règles des champs proviennent de la référence de l’API PoYo. Pour savoir ce qu’est le modèle et comment il se compare, commencez par la présentation de l’Ideogram 4.6 API.
Étape 1 : soumettre une requête à l’Ideogram 4.6 API avec cURL
Créez une clé dans le tableau de bord PoYo et exportez-la sous le nom POYO_API_KEY. Gardez-la sur votre serveur, pas dans le code du navigateur.
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v4.6",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}'
Cette requête utilise les valeurs par défaut : size: auto (environ 2K), quality: medium, une image, soit 12 crédits ($0.06). Une soumission réussie renvoie code: 200 et un objet data avec task_id, status: "not_started" et created_time. C’est une tâche en file d’attente, pas une image. Vérifiez code dans le corps à chaque fois : certaines erreurs de validation reviennent avec HTTP 200 et code: 400.
Étape 2 : interroger le statut de la tâche
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Le statut passe par not_started, running, puis finished ou failed. Une tâche terminée liste une entrée par image dans data.files, chacune avec file_url et file_type: "image", et indique le montant facturé dans credits_amount. Une tâche échouée donne la raison dans error_message.
Étape 3 : une boucle de polling Python bornée
Cette boucle vérifie à la fois le statut HTTP et le code du corps, s’arrête sur failed, renvoie toutes les images quand n est supérieur à 1, et abandonne au bout de 10 minutes sans resoumettre.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
body = response.json()
if response.status_code >= 400 or body.get("code") != 200:
error = body.get("error") or {}
raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
return body["data"]
def run(model, input_body, max_wait=600):
task = checked(session.post(BASE + "/api/generate/submit",
json={"model": model, "input": input_body},
timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
return images, task.get("credits_amount")
raise TimeoutError("Still running, check this task later: " + task_id)
images, credits = run("ideogram-v4.6", {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "1728x2304",
"quality": "high",
"n": 2,
})
print(images, credits)
1728x2304 est une taille 3:4 de 3,981,312 pixels, sous la limite de 4,194,304 pixels : les deux images sont donc facturées au tarif 2K high, soit 2 × 20 = 40 crédits ($0.20). Un timeout signifie « interrogez à nouveau le même ID de tâche plus tard ». Resoumettre lancerait une seconde tâche facturable. La même fonction run() fonctionne pour les éditions : passez "ideogram-v4.6-edit" comme modèle.
Tous les modes d’entrée de l’Ideogram 4.6 API
Tous les champs vont dans input. L’ID de modèle et un callback_url facultatif se placent au niveau racine.
Text-to-image en 4K
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 représente 6,291,456 pixels, au-delà de 4,194,304 : c’est donc le palier 4K, et very_low n’est pas autorisé à cette taille.
Arrière-plan transparent et seed fixe
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A flat sticker of a smiling coffee cup",
"size": "1:1 HD",
"quality": "low",
"background": "transparent",
"seed": 42
}
}
transparent renvoie une image avec un canal alpha ; opaque force un arrière-plan uni. Envoyez le même corps avec le même seed pour reproduire un résultat.
Édition classique
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
Une édition classique régénère l’image à partir du prompt. image_urls doit être un tableau contenant exactement une image, sous forme d’URL HTTP(S) publique ou de data URI base64. Pour envoyer des fichiers locaux, téléversez-les d’abord avec l’endpoint de téléversement de fichiers de PoYo.
Restyler avec une image de référence
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Restyle the product shot to match the reference",
"image_urls": [
"https://example.com/product.png"
],
"reference_image_urls": [
"https://example.com/style.png"
],
"size": "2048x2048",
"quality": "low",
"n": 2
}
}
Jusqu’à 4 références sont autorisées, ou 3 avec un masque. Un size personnalisé est accepté ici, car il s’agit d’une édition classique sans masque.
Édition haute précision de l’image entière
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
"image_urls": [
"https://example.com/poster.png"
],
"edit_precision": "high",
"context_window": "none",
"size": "auto",
"quality": "high"
}
}
C’est le corps de notre édition du jour du lancement (tâche 672JRU198S22NS8D, 20 novembre 2026), avec l’URL de la source remplacée. La source était une affiche 2304×3072 ; la sortie a gardé cette taille et n’a modifié que la ligne de date, et la tâche a été facturée 120 crédits ($0.60), le tarif d’édition 4K high.
Édition masquée localisée
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change the sign text to \"OPEN LATE\"",
"image_urls": [
"https://example.com/storefront.png"
],
"mask_url": "https://example.com/sign-mask.png",
"edit_precision": "high",
"context_window": "auto",
"quality": "high"
}
}
Le masque doit avoir les dimensions de la source et contenir à la fois des zones noires (à éditer) et blanches (à conserver). Avec context_window: auto, seule la région autour du masque est éditée, à la résolution de la source. Un masque trop grand bascule vers une édition de l’image entière.
Règles de validation des champs
Validez de votre côté avant de soumettre, pour que les requêtes invalides échouent vite :
| Champ | Règle |
|---|---|
model | ideogram-v4.6 ou ideogram-v4.6-edit |
prompt | Obligatoire, de 1 à 10,000 caractères, pas uniquement des espaces |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 ou WIDTHxHEIGHT avec un x minuscule |
| Taille personnalisée | Chaque côté entre 256 et 4096 et multiple de 32 ; ratio d’aspect compris entre 1:6 et 6:1 |
quality | very_low seulement quand la sortie fait au plus 4,194,304 pixels |
n | Entier de 1 à 8 ; les chaînes et les booléens sont rejetés |
image_urls | Édition uniquement ; tableau contenant exactement une image |
mask_url, edit_precision: high | Exigent size: auto (ou aucun size) |
background | Rejeté quand edit_precision vaut high |
context_window: auto | Exige mask_url et edit_precision: high |
| Champs inconnus | Rejetés avec une erreur unsupported fields |
Exemples : 2304x3072 passe (les deux côtés sont multiples de 32) ; 1296x3168 échoue car 1296 n’est pas un multiple de 32, alors qu’Ideogram 4.5 l’acceptait ; 4096x512 échoue (ratio 8:1) ; very_low en 2048x3072 échoue.
Erreurs à gérer
code | Signification | Que faire |
|---|---|---|
| 400 | Paramètres invalides | Corrigez le corps ; ne réessayez pas sans modification |
| 401 | Clé API absente ou invalide | Vérifiez l’en-tête Authorization: Bearer |
| 402 | Crédits insuffisants | Rechargez, puis resoumettez |
| 429 | Limite de débit dépassée | Ralentissez et réessayez plus tard |
| 500, 502, 503 | Erreur serveur, amont ou de disponibilité | Réessayez avec backoff ; vérifiez d’abord si un ID de tâche a déjà été renvoyé |
Une tâche qui passe à failed indique la raison dans error_message. Consultez les codes d’erreur pour la liste complète.
Utiliser un callback au lieu du polling
Ajoutez "callback_url": "https://your-app.example.com/poyo-webhook" au niveau racine du corps, pas dans input. Quand la tâche se termine ou échoue, PoYo envoie en POST les données de la tâche à cette URL, signées en HMAC-SHA256 dans l’en-tête X-Webhook-Signature ; la documentation des webhooks donne la règle de signature. Gardez un polling lent en secours pour les callbacks qui n’arrivent jamais.
Comment votre première facture est calculée
L’Ideogram 4.6 API facture par image produite : prix du palier de qualité et de taille × n. 1 crédit = $0.005.
| Requête | Palier | Montant |
|---|---|---|
Valeurs par défaut (auto, medium, n: 1) | Text-to-image medium 2K | 12 crédits ($0.06) |
very_low, 3:4, n: 1 | Text-to-image very_low 2K | 1.6 crédits ($0.008) |
high, 1728x2304, n: 2 | Text-to-image high 2K | 40 crédits ($0.20) |
high, 2304x3072, n: 1 | Text-to-image high 4K | 40 crédits ($0.20) |
Édition haute précision d’une source 2304×3072, high | Édition high 4K | 120 crédits ($0.60) |
Les lignes very_low et 2304x3072 correspondent à ce qui a été facturé pour nos tâches du jour du lancement. Pour les éditions avec size: auto, le prix est estimé à partir de la taille de l’image source et réglé sur l’image livrée, jamais au-dessus de l’estimation. L’article sur les prix donne d’autres exemples chiffrés.
Questions fréquentes
L’Ideogram 4.6 API est-elle compatible avec le SDK OpenAI ?
Non. C’est une API de tâches asynchrones : soumettez à /api/generate/submit, puis interrogez /api/generate/status/{task_id} ou recevez un callback. requests, fetch ou cURL suffisent.
Comment éditer une image avec l’Ideogram 4.6 API ?
Appelez ideogram-v4.6-edit avec une URL dans image_urls et la modification dans prompt. Ajoutez edit_precision: high pour conserver les pixels que vous n’avez pas demandé de modifier.
Puis-je envoyer des images de référence à ideogram-v4.6 ?
Non. Sur PoYo, les références vont dans reference_image_urls sur ideogram-v4.6-edit, jusqu’à 4, ou 3 avec un masque.
Combien d’images renvoie une requête à l’Ideogram 4.6 API ?
De 1 à 8, à régler avec n. Chaque image est facturée au prix du palier.
Pourquoi ma requête à l’Ideogram 4.6 API a-t-elle été rejetée pour sa taille ?
Les côtés personnalisés doivent être des multiples de 32 entre 256 et 4096, et les masques ou les éditions haute précision exigent size: auto.