
Deze Ideogram 4.6 API-gids brengt je van een API-key naar een afgewerkte afbeelding in cURL en Python, en behandelt daarna elke invoermodus die het PoYo-schema accepteert: text-to-image op preset- of aangepaste formaten, transparante achtergronden, reguliere bewerkingen, gemaskeerde bewerkingen, referentieafbeeldingen en bewerkingen met hoge precisie. Text-to-image gebruikt het model-ID ideogram-v4.6 en bewerken gebruikt ideogram-v4.6-edit; beide staan op de Ideogram 4.6-modelpagina.
De veldregels komen uit de PoYo API-referentie. Wil je eerst weten wat het model is en hoe het zich verhoudt, begin dan met het overzicht van de Ideogram 4.6 API.
Stap 1: een Ideogram 4.6 API-request indienen met cURL
Maak een key aan in het PoYo-dashboard en exporteer die als POYO_API_KEY. Houd hem op je server, niet in browsercode.
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\""
}
}'
Dit gebruikt de standaardwaarden: size: auto (ongeveer 2K), quality: medium, één afbeelding, dus het kost 12 credits ($0.06). Een geslaagde indiening geeft code: 200 terug en een data-object met task_id, status: "not_started" en created_time. Dat is een taak in de wachtrij, geen afbeelding. Controleer elke keer code in de body: sommige validatiefouten komen terug met HTTP 200 en code: 400.
Stap 2: de taakstatus pollen
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
De status gaat van not_started naar running en daarna naar finished of failed. Een afgeronde taak toont in data.files één item per afbeelding, elk met file_url en file_type: "image", en meldt de afschrijving in credits_amount. Een mislukte taak legt de oorzaak uit in error_message.
Stap 3: een begrensde Python-pollinglus
Deze lus controleert zowel de HTTP-status als de code in de body, stopt bij failed, geeft alle afbeeldingen terug als n groter is dan 1, en geeft het na 10 minuten op zonder opnieuw in te dienen.
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 is een 3:4-formaat van 3,981,312 pixels, onder de grens van 4,194,304 pixels, dus de twee afbeeldingen worden afgerekend tegen het 2K-high-tarief: 2 × 20 = 40 credits ($0.20). Een timeout betekent "controleer hetzelfde taak-ID later opnieuw". Opnieuw indienen zou een tweede betaalde taak starten. Dezelfde run() werkt voor bewerkingen: geef "ideogram-v4.6-edit" mee als model.
Alle invoermodi van de Ideogram 4.6 API
Alle velden horen binnen input. Het model-ID en een optionele callback_url staan op het hoogste niveau.
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 is 6,291,456 pixels, boven 4,194,304, dus dit is het 4K-niveau en very_low is bij dit formaat niet toegestaan.
Transparante achtergrond en een vaste seed
{
"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 geeft een afbeelding met alfakanaal terug; opaque dwingt een effen achtergrond af. Stuur dezelfde body met dezelfde seed om een resultaat te herhalen.
Reguliere bewerking
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
Een reguliere bewerking genereert de afbeelding opnieuw vanuit de prompt. image_urls moet een array zijn met precies één afbeelding, als publieke HTTP(S)-URL of base64-data-URI. Wil je lokale bestanden sturen, upload ze dan eerst met het file-upload-endpoint van PoYo.
Restylen met een referentieafbeelding
{
"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
}
}
Tot 4 referenties zijn toegestaan, of 3 met een masker. Een aangepaste size is hier toegestaan omdat dit een reguliere bewerking zonder masker is.
Bewerking met hoge precisie van de hele afbeelding
{
"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"
}
}
Dit is de body van onze bewerking op de launchdag (taak 672JRU198S22NS8D, 20 november 2026), met de bron-URL vervangen. De bron was een poster van 2304×3072; de output behield dat formaat en wijzigde alleen de datumregel, en de taak kostte 120 credits ($0.60), het 4K-high-bewerkingstarief.
Lokale gemaskeerde bewerking
{
"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"
}
}
Het masker moet dezelfde afmetingen hebben als de bron en zowel zwarte (bewerken) als witte (behouden) gebieden bevatten. Met context_window: auto wordt alleen het gebied rond het masker bewerkt, op de resolutie van de bron. Een masker dat te groot is, valt terug op bewerking van de hele afbeelding.
Validatieregels per veld
Valideer aan jouw kant vóór het indienen, zodat foute requests snel falen:
| Veld | Regel |
|---|---|
model | ideogram-v4.6 of ideogram-v4.6-edit |
prompt | Verplicht, 1 tot 10,000 tekens, niet alleen witruimte |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 of WIDTHxHEIGHT met een kleine x |
| Aangepast formaat | Elke zijde 256 tot 4096 en een veelvoud van 32; beeldverhouding tussen 1:6 en 6:1 |
quality | very_low alleen als de output maximaal 4,194,304 pixels is |
n | Geheel getal 1 tot 8; strings en booleans worden geweigerd |
image_urls | Alleen bewerken; array met precies één afbeelding |
mask_url, edit_precision: high | Vereisen size: auto (of geen size) |
background | Geweigerd als edit_precision gelijk is aan high |
context_window: auto | Vereist mask_url en edit_precision: high |
| Onbekende velden | Geweigerd met een unsupported fields-fout |
Voorbeelden: 2304x3072 slaagt (beide zijden veelvouden van 32); 1296x3168 faalt omdat 1296 geen veelvoud van 32 is, ook al accepteerde Ideogram 4.5 het; 4096x512 faalt (verhouding 8:1); very_low bij 2048x3072 faalt.
Fouten die je moet afhandelen
code | Betekenis | Wat te doen |
|---|---|---|
| 400 | Ongeldige parameters | Corrigeer de body; niet ongewijzigd opnieuw proberen |
| 401 | Ontbrekende of ongeldige API-key | Controleer de Authorization: Bearer-header |
| 402 | Onvoldoende credits | Waardeer op en dien opnieuw in |
| 429 | Rate limit overschreden | Wacht en probeer het later opnieuw |
| 500, 502, 503 | Server-, upstream- of beschikbaarheidsfout | Opnieuw proberen met backoff; controleer eerst of er al een taak-ID is teruggegeven |
Een taak die failed bereikt, vermeldt de reden in error_message. Zie Error Codes voor de volledige lijst.
Een callback gebruiken in plaats van polling
Voeg "callback_url": "https://your-app.example.com/poyo-webhook" toe op het hoogste niveau van de body, niet binnen input. Als de taak klaar is of mislukt, POST PoYo de taakgegevens naar die URL, ondertekend met HMAC-SHA256 in de header X-Webhook-Signature; de webhook-docs beschrijven de handtekeningregel. Houd een trage polling-fallback aan voor callbacks die nooit aankomen.
Hoe je eerste rekening wordt berekend
De Ideogram 4.6 API rekent per outputafbeelding af: prijs van het kwaliteits- en formaatniveau × n. 1 credit = $0.005.
| Request | Niveau | Afschrijving |
|---|---|---|
Standaardwaarden (auto, medium, n: 1) | Text-to-image medium 2K | 12 credits ($0.06) |
very_low, 3:4, n: 1 | Text-to-image very_low 2K | 1.6 credits ($0.008) |
high, 1728x2304, n: 2 | Text-to-image high 2K | 40 credits ($0.20) |
high, 2304x3072, n: 1 | Text-to-image high 4K | 40 credits ($0.20) |
Bewerking met hoge precisie van een 2304×3072-bron, high | Bewerken high 4K | 120 credits ($0.60) |
De rijen very_low en 2304x3072 komen overeen met wat onze taken op de launchdag kostten. Bij bewerkingen met size: auto wordt de prijs geoffreerd op basis van het formaat van de bronafbeelding en afgerekend op de geleverde afbeelding, nooit boven de offerte. Het prijsartikel heeft meer uitgewerkte voorbeelden.
Veelgestelde vragen
Is de Ideogram 4.6 API compatibel met de OpenAI SDK?
Nee. Het is een asynchrone taak-API: dien in bij /api/generate/submit en poll daarna /api/generate/status/{task_id} of ontvang een callback. Gewoon requests, fetch of cURL werkt.
Hoe bewerk ik een afbeelding met de Ideogram 4.6 API?
Roep ideogram-v4.6-edit aan met één URL in image_urls en de wijziging in prompt. Voeg edit_precision: high toe om de pixels te behouden die je niet wilde wijzigen.
Kan ik referentieafbeeldingen naar ideogram-v4.6 sturen?
Nee. Op PoYo horen referenties in reference_image_urls bij ideogram-v4.6-edit, tot 4, of 3 met een masker.
Hoeveel afbeeldingen geeft één Ideogram 4.6 API-request terug?
1 tot 8, ingesteld met n. Elke afbeelding wordt afgerekend tegen de prijs van het niveau.
Waarom werd mijn Ideogram 4.6 API-request geweigerd vanwege het formaat?
Aangepaste zijden moeten veelvouden van 32 zijn tussen 256 en 4096, en maskers of bewerkingen met hoge precisie vereisen size: auto.