
Questa guida alla Ideogram 4.6 API ti porta da una chiave API a un'immagine finita in cURL e Python, poi copre ogni modalità di input che lo schema di PoYo accetta: text-to-image con dimensioni preset o personalizzate, sfondi trasparenti, modifiche regolari, modifiche con maschera, immagini di riferimento e modifiche ad alta precisione. Il text-to-image usa l'ID modello ideogram-v4.6 e la modifica usa ideogram-v4.6-edit; entrambi sono elencati nella pagina del modello Ideogram 4.6.
Le regole dei campi vengono dal riferimento API di PoYo. Per sapere cos'è il modello e come si confronta con gli altri, parti dalla panoramica della Ideogram 4.6 API.
Passo 1: invia una richiesta alla Ideogram 4.6 API con cURL
Crea una chiave nella dashboard di PoYo ed esportala come POYO_API_KEY. Tienila sul tuo server, non nel codice del browser.
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\""
}
}'
Questa richiesta usa i valori predefiniti: size: auto (circa 2K), quality: medium, un'immagine, quindi costa 12 crediti ($0.06). Un invio riuscito restituisce code: 200 e un oggetto data con task_id, status: "not_started" e created_time. È un task in coda, non un'immagine. Controlla sempre code nel body: alcuni errori di validazione tornano con HTTP 200 e code: 400.
Passo 2: interroga lo stato del task
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Lo stato passa da not_started a running e poi a finished o failed. Un task completato elenca una voce per immagine in data.files, ciascuna con file_url e file_type: "image", e riporta l'addebito in credits_amount. Un task fallito spiega il motivo in error_message.
Passo 3: un ciclo di polling in Python con limite di tempo
Questo ciclo controlla sia lo stato HTTP sia il code del body, si ferma su failed, restituisce tutte le immagini quando n è maggiore di 1 e rinuncia dopo 10 minuti senza reinviare.
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 è una dimensione 3:4 di 3,981,312 pixel, sotto la soglia di 4,194,304 pixel, quindi le due immagini sono fatturate alla tariffa 2K high: 2 × 20 = 40 crediti ($0.20). Un timeout significa "ricontrolla lo stesso ID task più tardi". Reinviare avvierebbe un secondo task a pagamento. La stessa run() funziona per le modifiche: passa "ideogram-v4.6-edit" come modello.
Tutte le modalità di input della Ideogram 4.6 API
Tutti i campi vanno dentro input. L'ID modello e un eventuale callback_url stanno al livello principale.
Text-to-image in 4K
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 equivale a 6,291,456 pixel, sopra 4,194,304, quindi è la fascia 4K e very_low non è consentito a questa dimensione.
Sfondo trasparente e seed fisso
{
"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 restituisce un'immagine con canale alfa; opaque forza uno sfondo pieno. Invia lo stesso body con lo stesso seed per ripetere un risultato.
Modifica regolare
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
Una modifica regolare rigenera l'immagine a partire dal prompt. image_urls deve essere un array con esattamente un'immagine, come URL HTTP(S) pubblico o data URI base64. Per inviare file locali, caricali prima con l'endpoint di upload dei file di PoYo.
Cambio di stile con un'immagine di riferimento
{
"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
}
}
Sono ammessi fino a 4 riferimenti, o 3 con una maschera. Qui è consentito un size personalizzato perché si tratta di una modifica regolare senza maschera.
Modifica ad alta precisione dell'intera immagine
{
"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"
}
}
È il body della nostra modifica del giorno di lancio (task 672JRU198S22NS8D, 20 novembre 2026), con l'URL della sorgente sostituito. La sorgente era un poster 2304×3072; l'output ha mantenuto quella dimensione e cambiato solo la riga della data, e il task è stato addebitato 120 crediti ($0.60), la tariffa di modifica 4K high.
Modifica localizzata con maschera
{
"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"
}
}
La maschera deve avere le stesse dimensioni della sorgente e contenere sia aree nere (da modificare) sia bianche (da mantenere). Con context_window: auto viene modificata solo la regione attorno alla maschera, alla risoluzione della sorgente. Una maschera troppo grande ricade sulla modifica dell'intera immagine.
Regole di validazione dei campi
Valida dal tuo lato prima di inviare, così le richieste errate falliscono subito:
| Campo | Regola |
|---|---|
model | ideogram-v4.6 o ideogram-v4.6-edit |
prompt | Obbligatorio, da 1 a 10,000 caratteri, non solo spazi |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 o WIDTHxHEIGHT con x minuscola |
| Dimensione personalizzata | Ogni lato da 256 a 4096 e multiplo di 32; proporzioni tra 1:6 e 6:1 |
quality | very_low solo quando l'output è al massimo 4,194,304 pixel |
n | Intero da 1 a 8; stringhe e booleani vengono rifiutati |
image_urls | Solo modifica; array con esattamente un'immagine |
mask_url, edit_precision: high | Richiedono size: auto (o nessun size) |
background | Rifiutato quando edit_precision è high |
context_window: auto | Richiede mask_url e edit_precision: high |
| Campi sconosciuti | Rifiutati con un errore unsupported fields |
Esempi: 2304x3072 passa (entrambi i lati sono multipli di 32); 1296x3168 fallisce perché 1296 non è multiplo di 32, anche se Ideogram 4.5 lo accettava; 4096x512 fallisce (proporzione 8:1); very_low a 2048x3072 fallisce.
Errori da gestire
code | Significato | Cosa fare |
|---|---|---|
| 400 | Parametri non validi | Correggi il body; non riprovare senza modifiche |
| 401 | Chiave API mancante o non valida | Controlla l'header Authorization: Bearer |
| 402 | Crediti insufficienti | Ricarica, poi reinvia |
| 429 | Limite di richieste superato | Attendi e riprova più tardi |
| 500, 502, 503 | Errore del server, dell'upstream o di disponibilità | Riprova con backoff; prima verifica se è già stato restituito un ID task |
Un task che arriva a failed riporta il motivo in error_message. Consulta Error Codes per l'elenco completo.
Usa un callback invece del polling
Aggiungi "callback_url": "https://your-app.example.com/poyo-webhook" al livello principale del body, non dentro input. Quando il task termina o fallisce, PoYo invia con POST i dati del task a quell'URL, firmati con HMAC-SHA256 nell'header X-Webhook-Signature; la documentazione dei webhook riporta la regola della firma. Mantieni un polling lento come fallback per i callback che non arrivano mai.
Come viene calcolato il tuo primo addebito
La Ideogram 4.6 API addebita per immagine in output: prezzo della fascia di qualità e dimensione × n. 1 credito = $0.005.
| Richiesta | Fascia | Addebito |
|---|---|---|
Valori predefiniti (auto, medium, n: 1) | Text-to-image medium 2K | 12 crediti ($0.06) |
very_low, 3:4, n: 1 | Text-to-image very_low 2K | 1.6 crediti ($0.008) |
high, 1728x2304, n: 2 | Text-to-image high 2K | 40 crediti ($0.20) |
high, 2304x3072, n: 1 | Text-to-image high 4K | 40 crediti ($0.20) |
Modifica ad alta precisione di una sorgente 2304×3072, high | Modifica high 4K | 120 crediti ($0.60) |
Le righe very_low e 2304x3072 corrispondono a quanto addebitato per i nostri task del giorno di lancio. Per le modifiche con size: auto, il prezzo viene preventivato in base alla dimensione dell'immagine sorgente e saldato sull'immagine consegnata, mai sopra il preventivo. L'articolo sui prezzi contiene altri esempi calcolati.
Domande frequenti
La Ideogram 4.6 API è compatibile con l'SDK di OpenAI?
No. È un'API a task asincroni: invia a /api/generate/submit, poi interroga /api/generate/status/{task_id} o ricevi un callback. Funzionano requests, fetch o cURL semplici.
Come modifico un'immagine con la Ideogram 4.6 API?
Chiama ideogram-v4.6-edit con un URL in image_urls e la modifica in prompt. Aggiungi edit_precision: high per mantenere i pixel che non hai chiesto di cambiare.
Posso inviare immagini di riferimento a ideogram-v4.6?
No. Su PoYo i riferimenti vanno in reference_image_urls su ideogram-v4.6-edit, fino a 4, o 3 con una maschera.
Quante immagini restituisce una richiesta alla Ideogram 4.6 API?
Da 1 a 8, impostate con n. Ogni immagine è fatturata al prezzo della fascia.
Perché la mia richiesta alla Ideogram 4.6 API è stata rifiutata per la dimensione?
I lati personalizzati devono essere multipli di 32 tra 256 e 4096, e le maschere o le modifiche ad alta precisione richiedono size: auto.