
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:
| Felt | Regel |
|---|---|
model | ideogram-v4.6 eller ideogram-v4.6-edit |
prompt | Påkrevd, 1 til 10,000 tegn, ikke bare mellomrom |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 eller WIDTHxHEIGHT med liten x |
| Egendefinert størrelse | Hver side 256 til 4096 og et multiplum av 32; sideforhold mellom 1:6 og 6:1 |
quality | very_low bare når resultatet er maks 4,194,304 piksler |
n | Heltall 1 til 8; strenger og booleans avvises |
image_urls | Bare redigering; array med nøyaktig ett bilde |
mask_url, edit_precision: high | Krever size: auto (eller ingen size) |
background | Avvises når edit_precision er high |
context_window: auto | Krever mask_url og edit_precision: high |
| Ukjente felter | Avvises 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
code | Betydning | Hva du gjør |
|---|---|---|
| 400 | Ugyldige parametere | Rett body; ikke prøv på nytt uendret |
| 401 | Manglende eller ugyldig API-nøkkel | Sjekk headeren Authorization: Bearer |
| 402 | Ikke nok credits | Fyll på, og send på nytt |
| 429 | Rate limit overskredet | Vent, og prøv igjen senere |
| 500, 502, 503 | Server-, upstream- eller tilgjengelighetsfeil | Prø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.
| Request | Nivå | Belastning |
|---|---|---|
Standardverdier (auto, medium, n: 1) | Tekst-til-bilde medium 2K | 12 credits ($0.06) |
very_low, 3:4, n: 1 | Tekst-til-bilde very_low 2K | 1.6 credits ($0.008) |
high, 1728x2304, n: 2 | Tekst-til-bilde high 2K | 40 credits ($0.20) |
high, 2304x3072, n: 1 | Tekst-til-bilde high 4K | 40 credits ($0.20) |
Høypresisjonsredigering av en 2304×3072-kilde, high | Redigering high 4K | 120 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.