
Denne Ideogram 4.6 API-guide tager dig fra en API-nøgle til et færdigt billede i cURL og Python og gennemgår derefter alle inputtilstande, som PoYo-skemaet accepterer: tekst-til-billede i preset- eller brugerdefinerede størrelser, transparente baggrunde, almindelige redigeringer, maskerede redigeringer, referencebilleder og højpræcisionsredigeringer. Tekst-til-billede bruger model-ID'et ideogram-v4.6, og redigering bruger ideogram-v4.6-edit; begge findes på modelsiden for Ideogram 4.6.
Feltreglerne kommer fra PoYos API-reference. Vil du vide, hvad modellen er, og hvordan den klarer sig i sammenligning, så start med oversigten over Ideogram 4.6 API.
Trin 1: send en Ideogram 4.6 API-request med cURL
Opret en nøgle i PoYo-dashboardet, og eksportér den som POYO_API_KEY. Hold den på din server, ikke i browserkode.
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 bruger standardværdierne: size: auto (ca. 2K), quality: medium, ét billede, så det koster 12 credits ($0.06). En vellykket indsendelse returnerer code: 200 og et data-objekt med task_id, status: "not_started" og created_time. Det er en task i kø, ikke et billede. Tjek code i body hver gang: nogle valideringsfejl kommer tilbage med HTTP 200 og code: 400.
Trin 2: poll task-status
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Status går gennem not_started, running og derefter finished eller failed. En færdig task har én post pr. billede i data.files, hver med file_url og file_type: "image", og rapporterer prisen i credits_amount. En fejlet task forklarer årsagen i error_message.
Trin 3: en begrænset Python-pollingløkke
Denne løkke tjekker både HTTP-status og code i body, stopper ved failed, returnerer alle billeder, når n er over 1, og giver op efter 10 minutter uden at sende igen.
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 pixels, under grænsen på 4,194,304 pixels, så de to billeder faktureres til 2K high-prisen: 2 × 20 = 40 credits ($0.20). En timeout betyder "tjek det samme task-ID igen senere". Hvis du sender igen, starter du en ekstra task, der faktureres. Den samme run() virker til redigeringer: angiv "ideogram-v4.6-edit" som model.
Alle inputtilstande i Ideogram 4.6 API
Alle felter ligger i input. Model-ID'et og en valgfri callback_url ligger på øverste niveau.
Tekst-til-billede 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 pixels, over 4,194,304, så dette er 4K-niveauet, og very_low er ikke tilladt i denne størrelse.
Transparent baggrund 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 billede med alfakanal; opaque tvinger en ensfarvet baggrund. Send den samme body med det samme seed for at gentage et resultat.
Almindelig redigering
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
En almindelig redigering genskaber billedet ud fra prompten. image_urls skal være et array med præcis ét billede, som offentlig HTTP(S)-URL eller base64 data-URI. Vil du sende lokale filer, så upload dem først med PoYos endpoint til filupload.
Restyling med et referencebillede
{
"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
}
}
Op til 4 referencer er tilladt, eller 3 med en maske. En brugerdefineret size er tilladt her, fordi det er en almindelig redigering uden maske.
Højpræcisionsredigering af hele billedet
{
"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 vores redigering på lanceringsdagen (task 672JRU198S22NS8D, 20. november 2026), med kilde-URL'en udskiftet. Kilden var en 2304×3072-plakat; outputtet beholdt den størrelse og ændrede kun datolinjen, og tasken blev opkrævet 120 credits ($0.60), 4K high-prisen for redigering.
Lokal maskeret 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 skal have kildens dimensioner og indeholde både sorte (redigér) og hvide (bevar) områder. Med context_window: auto redigeres kun området omkring masken i kildens opløsning. En maske, der er for stor, falder tilbage til redigering af hele billedet.
Valideringsregler for felter
Validér på din side før indsendelse, så forkerte requests fejler hurtigt:
| Felt | Regel |
|---|---|
model | ideogram-v4.6 eller ideogram-v4.6-edit |
prompt | Påkrævet, 1 til 10,000 tegn, ikke kun whitespace |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 eller WIDTHxHEIGHT med lille x |
| Brugerdefineret størrelse | Hver side 256 til 4096 og et multiplum af 32; billedformat mellem 1:6 og 6:1 |
quality | very_low kun når outputtet er højst 4,194,304 pixels |
n | Heltal 1 til 8; strenge og booleans afvises |
image_urls | Kun redigering; array med præcis ét billede |
mask_url, edit_precision: high | Kræver size: auto (eller ingen size) |
background | Afvises, når edit_precision er high |
context_window: auto | Kræver mask_url og edit_precision: high |
| Ukendte felter | Afvises med en unsupported fields-fejl |
Eksempler: 2304x3072 godkendes (begge sider er multipla af 32); 1296x3168 fejler, fordi 1296 ikke er et multiplum af 32, selvom Ideogram 4.5 accepterede den; 4096x512 fejler (forhold 8:1); very_low ved 2048x3072 fejler.
Fejl, der er værd at håndtere
code | Betydning | Hvad du skal gøre |
|---|---|---|
| 400 | Ugyldige parametre | Ret body; prøv ikke igen uændret |
| 401 | Manglende eller ugyldig API-nøgle | Tjek headeren Authorization: Bearer |
| 402 | Utilstrækkelige credits | Fyld op, og send igen |
| 429 | Rate limit overskredet | Vent, og prøv igen senere |
| 500, 502, 503 | Server-, upstream- eller tilgængelighedsfejl | Prøv igen med backoff; tjek først, om et task-ID allerede blev returneret |
En task, der ender i failed, angiver årsagen i error_message. Se Error Codes for den fulde liste.
Brug et callback i stedet for polling
Tilføj "callback_url": "https://your-app.example.com/poyo-webhook" på øverste niveau i body, ikke i input. Når tasken er færdig eller fejler, sender PoYo task-data med POST til den URL, signeret med HMAC-SHA256 i headeren X-Webhook-Signature; webhook-dokumentationen beskriver signaturreglen. Behold en langsom polling som reserve for callbacks, der aldrig kommer.
Sådan beregnes din første regning
Ideogram 4.6 API fakturerer pr. outputbillede: prisen for kvalitets- og størrelsesniveauet × n. 1 credit = $0.005.
| Request | Niveau | Pris |
|---|---|---|
Standardværdier (auto, medium, n: 1) | Tekst-til-billede medium 2K | 12 credits ($0.06) |
very_low, 3:4, n: 1 | Tekst-til-billede very_low 2K | 1.6 credits ($0.008) |
high, 1728x2304, n: 2 | Tekst-til-billede high 2K | 40 credits ($0.20) |
high, 2304x3072, n: 1 | Tekst-til-billede high 4K | 40 credits ($0.20) |
Højpræcisionsredigering af en 2304×3072-kilde, high | Redigering high 4K | 120 credits ($0.60) |
Rækkerne med very_low og 2304x3072 svarer til det, vores tasks på lanceringsdagen blev opkrævet. Ved redigeringer med size: auto beregnes prisen ud fra kildebilledets størrelse og afregnes på det leverede billede, aldrig over det oplyste beløb. Prisindlægget har flere gennemregnede eksempler.
Ofte stillede spørgsmål
Er Ideogram 4.6 API kompatibel med OpenAI SDK?
Nej. Det er et asynkront task-API: send til /api/generate/submit, og poll derefter /api/generate/status/{task_id} eller modtag et callback. Almindelig requests, fetch eller cURL virker.
Hvordan redigerer jeg et billede med Ideogram 4.6 API?
Kald ideogram-v4.6-edit med én URL i image_urls og ændringen i prompt. Tilføj edit_precision: high for at bevare de pixels, du ikke bad om at ændre.
Kan jeg sende referencebilleder til ideogram-v4.6?
Nej. På PoYo går referencer i reference_image_urls på ideogram-v4.6-edit, op til 4, eller 3 med en maske.
Hvor mange billeder returnerer én Ideogram 4.6 API-request?
1 til 8, angivet med n. Hvert billede faktureres til niveauprisen.
Hvorfor blev min Ideogram 4.6 API-request afvist på grund af størrelsen?
Brugerdefinerede sider skal være multipla af 32 mellem 256 og 4096, og masker eller højpræcisionsredigeringer kræver size: auto.