how-tos

Ideogram 4.6 API-gids: eerste afbeelding en bewerking in cURL en Python

Poyo.ai Team
9 min read
Share:

Ideogram 4.6 API-gids met cURL en Python

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:

VeldRegel
modelideogram-v4.6 of ideogram-v4.6-edit
promptVerplicht, 1 tot 10,000 tekens, niet alleen witruimte
sizeauto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 of WIDTHxHEIGHT met een kleine x
Aangepast formaatElke zijde 256 tot 4096 en een veelvoud van 32; beeldverhouding tussen 1:6 en 6:1
qualityvery_low alleen als de output maximaal 4,194,304 pixels is
nGeheel getal 1 tot 8; strings en booleans worden geweigerd
image_urlsAlleen bewerken; array met precies één afbeelding
mask_url, edit_precision: highVereisen size: auto (of geen size)
backgroundGeweigerd als edit_precision gelijk is aan high
context_window: autoVereist mask_url en edit_precision: high
Onbekende veldenGeweigerd 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

codeBetekenisWat te doen
400Ongeldige parametersCorrigeer de body; niet ongewijzigd opnieuw proberen
401Ontbrekende of ongeldige API-keyControleer de Authorization: Bearer-header
402Onvoldoende creditsWaardeer op en dien opnieuw in
429Rate limit overschredenWacht en probeer het later opnieuw
500, 502, 503Server-, upstream- of beschikbaarheidsfoutOpnieuw 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.

RequestNiveauAfschrijving
Standaardwaarden (auto, medium, n: 1)Text-to-image medium 2K12 credits ($0.06)
very_low, 3:4, n: 1Text-to-image very_low 2K1.6 credits ($0.008)
high, 1728x2304, n: 2Text-to-image high 2K40 credits ($0.20)
high, 2304x3072, n: 1Text-to-image high 4K40 credits ($0.20)
Bewerking met hoge precisie van een 2304×3072-bron, highBewerken high 4K120 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.

Share: