
Bu Ideogram 4.6 API rehberi sizi bir API anahtarından cURL ve Python ile tamamlanmış bir görsele götürür, ardından PoYo şemasının kabul ettiği tüm giriş modlarını ele alır: hazır veya özel boyutlarda metinden görsele üretim, şeffaf arka planlar, normal düzenlemeler, maskeli düzenlemeler, referans görseller ve yüksek hassasiyetli düzenlemeler. Metinden görsele üretim ideogram-v4.6 model kimliğini, düzenleme ise ideogram-v4.6-edit kimliğini kullanır; ikisi de Ideogram 4.6 model sayfasında listelenir.
Alan kuralları PoYo API referansından alınmıştır. Modelin ne olduğunu ve nasıl karşılaştırıldığını öğrenmek için Ideogram 4.6 API genel bakışıyla başlayın.
Adım 1: cURL ile bir Ideogram 4.6 API isteği gönderin
PoYo panelinde bir anahtar oluşturun ve onu POYO_API_KEY olarak dışa aktarın. Anahtarı tarayıcı kodunda değil, sunucunuzda tutun.
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\""
}
}'
Bu istek varsayılanları kullanır: size: auto (yaklaşık 2K), quality: medium, tek görsel; bu yüzden 12 kredi ($0.06) tutar. Başarılı bir gönderim code: 200 ve task_id, status: "not_started" ile created_time içeren bir data nesnesi döndürür. Bu bir görsel değil, kuyruğa alınmış bir görevdir. Gövdedeki code alanını her seferinde kontrol edin: bazı doğrulama hataları HTTP 200 ve code: 400 ile döner.
Adım 2: görev durumunu sorgulayın
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Durum sırasıyla not_started, running ve ardından finished veya failed olur. Tamamlanan bir görev, data.files içinde her görsel için file_url ve file_type: "image" içeren bir girdi listeler ve ücreti credits_amount alanında bildirir. Başarısız bir görev nedenini error_message alanında açıklar.
Adım 3: süre sınırlı bir Python sorgulama döngüsü
Bu döngü hem HTTP durumunu hem de gövdedeki code alanını kontrol eder, failed durumunda durur, n 1'den büyük olduğunda tüm görselleri döndürür ve yeniden göndermeden 10 dakika sonra vazgeçer.
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, 3,981,312 piksellik 3:4 bir boyuttur ve 4,194,304 piksel sınırının altında kalır; bu yüzden iki görsel 2K high fiyatından ücretlendirilir: 2 × 20 = 40 kredi ($0.20). Zaman aşımı "aynı görev kimliğini daha sonra tekrar kontrol edin" anlamına gelir. Yeniden göndermek, ücretlendirilen ikinci bir görev başlatır. Aynı run() düzenlemeler için de çalışır: model olarak "ideogram-v4.6-edit" verin.
Ideogram 4.6 API'nin tüm giriş modları
Tüm alanlar input içine yazılır. Model kimliği ve isteğe bağlı callback_url en üst düzeyde yer alır.
4K'da metinden görsele
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 6,291,456 piksel eder, yani 4,194,304'ün üzerindedir; bu nedenle bu istek 4K katmanındadır ve bu boyutta very_low kullanılamaz.
Şeffaf arka plan ve sabit bir 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 alfa kanallı bir görsel döndürür; opaque düz bir arka planı zorunlu kılar. Bir sonucu tekrarlamak için aynı gövdeyi aynı seed ile gönderin.
Normal düzenleme
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
Normal bir düzenleme görseli prompttan yeniden üretir. image_urls, herkese açık bir HTTP(S) URL'si veya base64 data URI olarak tam olarak bir görsel içeren bir dizi olmalıdır. Yerel dosyalar göndermek için önce onları PoYo'nun dosya yükleme uç noktasıyla yükleyin.
Bir referans görselle yeniden stillendirme
{
"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
}
}
En fazla 4 referansa, maskeyle birlikte ise 3 referansa izin verilir. Bu, maskesiz normal bir düzenleme olduğu için burada özel bir size kullanılabilir.
Görselin tamamında yüksek hassasiyetli düzenleme
{
"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"
}
}
Bu, lansman günü düzenlememizin gövdesidir (görev 672JRU198S22NS8D, 20 Kasım 2026); yalnızca kaynak URL'si değiştirildi. Kaynak 2304×3072 bir posterdi; çıktı bu boyutu korudu ve yalnızca tarih satırını değiştirdi. Görev, 4K high düzenleme fiyatı olan 120 kredi ($0.60) ile ücretlendirildi.
Yerel maskeli düzenleme
{
"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"
}
}
Maske, kaynakla aynı boyutlarda olmalı ve hem siyah (düzenle) hem de beyaz (koru) alanlar içermelidir. context_window: auto ile yalnızca maskenin çevresindeki bölge kaynak çözünürlüğünde düzenlenir. Çok büyük bir maske, görselin tamamını düzenlemeye geri döner.
Alan doğrulama kuralları
Hatalı isteklerin hızlıca başarısız olması için göndermeden önce kendi tarafınızda doğrulama yapın:
| Alan | Kural |
|---|---|
model | ideogram-v4.6 veya ideogram-v4.6-edit |
prompt | Zorunlu, 1 ila 10,000 karakter, yalnızca boşluktan oluşamaz |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 veya küçük harf x ile WIDTHxHEIGHT |
| Özel boyut | Her kenar 256 ila 4096 ve 32'nin katı; en-boy oranı 1:6 ile 6:1 arasında |
quality | very_low yalnızca çıktı en fazla 4,194,304 piksel olduğunda |
n | 1 ila 8 arası tam sayı; string ve boolean değerler reddedilir |
image_urls | Yalnızca düzenleme; tam olarak bir görsel içeren dizi |
mask_url, edit_precision: high | size: auto gerektirir (veya size olmadan) |
background | edit_precision değeri high olduğunda reddedilir |
context_window: auto | mask_url ve edit_precision: high gerektirir |
| Bilinmeyen alanlar | unsupported fields hatasıyla reddedilir |
Örnekler: 2304x3072 geçer (iki kenar da 32'nin katı); 1296x3168 başarısız olur, çünkü 1296 32'nin katı değildir, Ideogram 4.5 bunu kabul etmiş olsa bile; 4096x512 başarısız olur (oran 8:1); 2048x3072 boyutunda very_low başarısız olur.
Ele alınması gereken hatalar
code | Anlamı | Ne yapmalı |
|---|---|---|
| 400 | Geçersiz parametreler | Gövdeyi düzeltin; değiştirmeden yeniden denemeyin |
| 401 | Eksik veya geçersiz API anahtarı | Authorization: Bearer başlığını kontrol edin |
| 402 | Yetersiz kredi | Kredi yükleyin, ardından yeniden gönderin |
| 429 | Hız sınırı aşıldı | Bekleyin ve daha sonra yeniden deneyin |
| 500, 502, 503 | Sunucu, upstream veya erişilebilirlik hatası | Artan bekleme süresiyle yeniden deneyin; önce bir görev kimliğinin zaten dönüp dönmediğini kontrol edin |
failed durumuna ulaşan bir görev, nedeni error_message alanında taşır. Tam liste için Hata Kodları sayfasına bakın.
Sorgulama yerine callback kullanın
"callback_url": "https://your-app.example.com/poyo-webhook" alanını input içine değil, gövdenin en üst düzeyine ekleyin. Görev tamamlandığında veya başarısız olduğunda PoYo, görev verilerini X-Webhook-Signature başlığında HMAC-SHA256 ile imzalanmış olarak bu URL'ye POST eder; imza kuralı webhook dokümanlarında yer alıyor. Hiç gelmeyen callback'ler için yavaş bir sorgulama yedeği tutun.
İlk faturanız nasıl hesaplanır?
Ideogram 4.6 API, çıktı görseli başına ücretlendirir: kalite ve boyut katmanının fiyatı × n. 1 kredi = $0.005.
| İstek | Katman | Ücret |
|---|---|---|
Varsayılanlar (auto, medium, n: 1) | Metinden görsele medium 2K | 12 kredi ($0.06) |
very_low, 3:4, n: 1 | Metinden görsele very_low 2K | 1.6 kredi ($0.008) |
high, 1728x2304, n: 2 | Metinden görsele high 2K | 40 kredi ($0.20) |
high, 2304x3072, n: 1 | Metinden görsele high 4K | 40 kredi ($0.20) |
2304×3072 bir kaynağın yüksek hassasiyetli düzenlemesi, high | Düzenleme high 4K | 120 kredi ($0.60) |
very_low ve 2304x3072 satırları, lansman günü görevlerimizden alınan ücretlerle örtüşür. size: auto ile yapılan düzenlemelerde fiyat kaynak görselin boyutundan teklif edilir ve teslim edilen görsele göre kesinleşir; teklifin üzerine asla çıkmaz. Fiyat yazısında daha fazla hesaplanmış örnek var.
Sık sorulan sorular
Ideogram 4.6 API OpenAI SDK ile uyumlu mu?
Hayır. Bu asenkron bir görev API'sidir: /api/generate/submit adresine gönderin, ardından /api/generate/status/{task_id} sorgulayın veya bir callback alın. Düz requests, fetch veya cURL yeterlidir.
Ideogram 4.6 API ile bir görseli nasıl düzenlerim?
image_urls içinde tek bir URL ve prompt içinde değişiklikle ideogram-v4.6-edit çağırın. Değiştirilmesini istemediğiniz pikselleri korumak için edit_precision: high ekleyin.
ideogram-v4.6 modeline referans görseller gönderebilir miyim?
Hayır. PoYo'da referanslar ideogram-v4.6-edit üzerinde reference_image_urls alanına gider; en fazla 4, maskeyle 3.
Tek bir Ideogram 4.6 API isteği kaç görsel döndürür?
n ile ayarlanan 1 ila 8. Her görsel katman fiyatından ücretlendirilir.
Ideogram 4.6 API isteğim neden boyut nedeniyle reddedildi?
Özel kenarlar 256 ile 4096 arasında 32'nin katları olmalıdır; maskeler veya yüksek hassasiyetli düzenlemeler de size: auto gerektirir.