how-tos

Ideogram 4.6 API-veiledning: første bilde og redigering i cURL og Python

Poyo.ai Team
8 min read
Share:

Ideogram 4.6 API-veiledning med cURL og Python

Denne Ideogram 4.6 API-veiledningen tar deg fra en API-nøkkel til et ferdig bilde i cURL og Python, og går deretter gjennom alle inndatamodusene PoYo-skjemaet godtar: tekst-til-bilde i forhåndsinnstilte eller egendefinerte størrelser, transparente bakgrunner, vanlige redigeringer, maskerte redigeringer, referansebilder og høypresisjonsredigeringer. Tekst-til-bilde bruker modell-ID-en ideogram-v4.6, og redigering bruker ideogram-v4.6-edit; begge står på modellsiden for Ideogram 4.6.

Feltreglene kommer fra PoYos API-referanse. Vil du vite hva modellen er og hvordan den står seg, start med oversikten over Ideogram 4.6 API.

Trinn 1: send en Ideogram 4.6 API-request med cURL

Opprett en nøkkel i PoYo-dashbordet og eksporter den som POYO_API_KEY. Hold den på serveren din, ikke i nettleserkode.

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\""
    }
  }'

Dette bruker standardverdiene: size: auto (ca. 2K), quality: medium, ett bilde, så det koster 12 credits ($0.06). En vellykket innsending returnerer code: 200 og et data-objekt med task_id, status: "not_started" og created_time. Det er en task i kø, ikke et bilde. Sjekk code i body hver gang: noen valideringsfeil kommer tilbake med HTTP 200 og code: 400.

Trinn 2: poll task-statusen

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Statusen går gjennom not_started, running og deretter finished eller failed. En ferdig task har én oppføring per bilde i data.files, hver med file_url og file_type: "image", og rapporterer belastningen i credits_amount. En mislykket task forklarer årsaken i error_message.

Trinn 3: en begrenset Python-pollingløkke

Denne løkken sjekker både HTTP-status og code i body, stopper ved failed, returnerer alle bilder når n er over 1, og gir opp etter 10 minutter uten å sende på nytt.

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 er en 3:4-størrelse på 3,981,312 piksler, under grensen på 4,194,304 piksler, så de to bildene faktureres til 2K high-prisen: 2 × 20 = 40 credits ($0.20). En timeout betyr "sjekk samme task-ID igjen senere". Å sende på nytt ville starte en ny fakturerbar task. Samme run() fungerer for redigeringer: angi "ideogram-v4.6-edit" som modell.

Alle inndatamoduser i Ideogram 4.6 API

Alle felter ligger i input. Modell-ID-en og en valgfri callback_url ligger på toppnivå.

Tekst-til-bilde i 4K

{
  "model": "ideogram-v4.6",
  "input": {
    "prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
    "size": "2048x3072",
    "quality": "high",
    "n": 2
  }
}

2048x3072 er 6,291,456 piksler, over 4,194,304, så dette er 4K-nivået, og very_low er ikke tillatt i denne størrelsen.

Transparent bakgrunn og fast 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 returnerer et bilde med alfakanal; opaque tvinger frem en ensfarget bakgrunn. Send samme body med samme seed for å gjenta et resultat.

Vanlig redigering

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Replace the background with a blue photo studio",
    "image_urls": [
      "https://example.com/source.png"
    ]
  }
}

En vanlig redigering genererer bildet på nytt ut fra prompten. image_urls må være en array med nøyaktig ett bilde, som offentlig HTTP(S)-URL eller base64 data-URI. Vil du sende lokale filer, last dem først opp med PoYos endepunkt for filopplasting.

Restyling med et referansebilde

{
  "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
  }
}

Opptil 4 referanser er tillatt, eller 3 med en maske. En egendefinert size er tillatt her fordi dette er en vanlig redigering uten maske.

Høypresisjonsredigering av hele bildet

{
  "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"
  }
}

Dette er body-en fra redigeringen vår på lanseringsdagen (task 672JRU198S22NS8D, 20. november 2026), med kilde-URL-en byttet ut. Kilden var en 2304×3072-plakat; resultatet beholdt den størrelsen og endret bare datolinjen, og tasken ble belastet 120 credits ($0.60), 4K high-prisen for redigering.

Lokal maskert redigering

{
  "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"
  }
}

Masken må ha samme dimensjoner som kilden og inneholde både svarte (rediger) og hvite (behold) områder. Med context_window: auto redigeres bare området rundt masken, i kildens oppløsning. En maske som er for stor, faller tilbake til redigering av hele bildet.

Valideringsregler for felter

Valider på din side før innsending, slik at feil requests feiler raskt:

FeltRegel
modelideogram-v4.6 eller ideogram-v4.6-edit
promptPåkrevd, 1 til 10,000 tegn, ikke bare mellomrom
sizeauto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 eller WIDTHxHEIGHT med liten x
Egendefinert størrelseHver side 256 til 4096 og et multiplum av 32; sideforhold mellom 1:6 og 6:1
qualityvery_low bare når resultatet er maks 4,194,304 piksler
nHeltall 1 til 8; strenger og booleans avvises
image_urlsBare redigering; array med nøyaktig ett bilde
mask_url, edit_precision: highKrever size: auto (eller ingen size)
backgroundAvvises når edit_precision er high
context_window: autoKrever mask_url og edit_precision: high
Ukjente felterAvvises med en unsupported fields-feil

Eksempler: 2304x3072 godtas (begge sider er multipler av 32); 1296x3168 feiler fordi 1296 ikke er et multiplum av 32, selv om Ideogram 4.5 godtok den; 4096x512 feiler (forhold 8:1); very_low ved 2048x3072 feiler.

Feil som er verdt å håndtere

codeBetydningHva du gjør
400Ugyldige parametereRett body; ikke prøv på nytt uendret
401Manglende eller ugyldig API-nøkkelSjekk headeren Authorization: Bearer
402Ikke nok creditsFyll på, og send på nytt
429Rate limit overskredetVent, og prøv igjen senere
500, 502, 503Server-, upstream- eller tilgjengelighetsfeilPrøv igjen med backoff; sjekk først om en task-ID allerede ble returnert

En task som ender i failed, oppgir årsaken i error_message. Se Error Codes for hele listen.

Bruk et callback i stedet for polling

Legg til "callback_url": "https://your-app.example.com/poyo-webhook" på toppnivå i body, ikke i input. Når tasken er ferdig eller feiler, sender PoYo task-dataene med POST til den URL-en, signert med HMAC-SHA256 i headeren X-Webhook-Signature; webhook-dokumentasjonen beskriver signaturregelen. Behold en langsom polling som reserve for callbacks som aldri kommer.

Slik beregnes den første regningen din

Ideogram 4.6 API fakturerer per utdatabilde: prisen for kvalitets- og størrelsesnivået × n. 1 credit = $0.005.

RequestNivåBelastning
Standardverdier (auto, medium, n: 1)Tekst-til-bilde medium 2K12 credits ($0.06)
very_low, 3:4, n: 1Tekst-til-bilde very_low 2K1.6 credits ($0.008)
high, 1728x2304, n: 2Tekst-til-bilde high 2K40 credits ($0.20)
high, 2304x3072, n: 1Tekst-til-bilde high 4K40 credits ($0.20)
Høypresisjonsredigering av en 2304×3072-kilde, highRedigering high 4K120 credits ($0.60)

Radene med very_low og 2304x3072 samsvarer med det taskene våre på lanseringsdagen ble belastet. For redigeringer med size: auto beregnes prisen ut fra kildebildets størrelse og gjøres opp på det leverte bildet, aldri over det oppgitte beløpet. Prisinnlegget har flere utregnede eksempler.

Ofte stilte spørsmål

Er Ideogram 4.6 API kompatibel med OpenAI SDK? Nei. Det er et asynkront task-API: send til /api/generate/submit, og poll deretter /api/generate/status/{task_id} eller motta et callback. Vanlig requests, fetch eller cURL fungerer.

Hvordan redigerer jeg et bilde med Ideogram 4.6 API? Kall ideogram-v4.6-edit med én URL i image_urls og endringen i prompt. Legg til edit_precision: high for å beholde pikslene du ikke ba om å endre.

Kan jeg sende referansebilder til ideogram-v4.6? Nei. På PoYo går referanser i reference_image_urls på ideogram-v4.6-edit, opptil 4, eller 3 med en maske.

Hvor mange bilder returnerer én Ideogram 4.6 API-request? 1 til 8, angitt med n. Hvert bilde faktureres til nivåprisen.

Hvorfor ble Ideogram 4.6 API-requesten min avvist på grunn av størrelsen? Egendefinerte sider må være multipler av 32 mellom 256 og 4096, og masker eller høypresisjonsredigeringer krever size: auto.

Share: