
Ten poradnik Ideogram 4.6 API prowadzi od klucza API do gotowego obrazu w cURL i Pythonie, a potem omawia każdy tryb wejścia akceptowany przez schemat PoYo: tekst-na-obraz w rozmiarach z presetów lub własnych, przezroczyste tła, zwykłe edycje, edycje z maską, obrazy referencyjne i edycje wysokiej precyzji. Tekst-na-obraz używa ID modelu ideogram-v4.6, a edycja ideogram-v4.6-edit; oba są wymienione na stronie modelu Ideogram 4.6.
Reguły pól pochodzą z dokumentacji PoYo API. Czym jest model i jak wypada na tle innych, przeczytasz w przeglądzie Ideogram 4.6 API.
Krok 1: wyślij żądanie do Ideogram 4.6 API przez cURL
Utwórz klucz w panelu PoYo i wyeksportuj go jako POYO_API_KEY. Trzymaj go na serwerze, nie w kodzie przeglądarki.
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\""
}
}'
To żądanie używa wartości domyślnych: size: auto (ok. 2K), quality: medium, jeden obraz, więc kosztuje 12 credits ($0.06). Udane wysłanie zwraca code: 200 i obiekt data z task_id, status: "not_started" i created_time. To zadanie w kolejce, a nie obraz. Za każdym razem sprawdzaj code w ciele odpowiedzi: niektóre błędy walidacji wracają z HTTP 200 i code: 400.
Krok 2: odpytuj status zadania
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Status przechodzi przez not_started, running, a następnie finished lub failed. Zakończone zadanie wymienia w data.files po jednym wpisie na obraz, każdy z file_url i file_type: "image", i podaje pobraną kwotę w credits_amount. Zadanie zakończone błędem wyjaśnia przyczynę w error_message.
Krok 3: ograniczona czasowo pętla odpytywania w Pythonie
Ta pętla sprawdza zarówno status HTTP, jak i code w ciele, zatrzymuje się na failed, zwraca wszystkie obrazy, gdy n jest większe niż 1, i poddaje się po 10 minutach bez ponownego wysyłania.
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 to rozmiar 3:4 o 3,981,312 pikselach, poniżej granicy 4,194,304 pikseli, więc oba obrazy są rozliczane według stawki 2K high: 2 × 20 = 40 credits ($0.20). Timeout oznacza „sprawdź to samo ID zadania później”. Ponowne wysłanie uruchomiłoby drugie płatne zadanie. Ta sama funkcja run() działa dla edycji: przekaż "ideogram-v4.6-edit" jako model.
Wszystkie tryby wejścia Ideogram 4.6 API
Wszystkie pola trafiają do input. ID modelu i opcjonalny callback_url są na najwyższym poziomie.
Tekst-na-obraz w 4K
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 to 6,291,456 pikseli, więcej niż 4,194,304, więc to próg 4K i very_low nie jest dozwolone w tym rozmiarze.
Przezroczyste tło i stały 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 zwraca obraz z kanałem alfa; opaque wymusza jednolite tło. Wyślij to samo ciało z tym samym seed, aby powtórzyć wynik.
Zwykła edycja
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
Zwykła edycja generuje obraz od nowa na podstawie promptu. image_urls musi być tablicą z dokładnie jednym obrazem, jako publiczny URL HTTP(S) lub base64 data URI. Aby wysłać pliki lokalne, najpierw prześlij je przez endpoint przesyłania plików PoYo.
Zmiana stylu według obrazu referencyjnego
{
"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
}
}
Dozwolone są do 4 referencje lub 3 z maską. Własny size jest tu dozwolony, bo to zwykła edycja bez maski.
Edycja wysokiej precyzji całego obrazu
{
"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"
}
}
To ciało naszej edycji z dnia premiery (zadanie 672JRU198S22NS8D, 20 listopada 2026) z podmienionym URL źródła. Źródłem był plakat 2304×3072; wynik zachował ten rozmiar i zmienił tylko wiersz z datą, a za zadanie pobrano 120 credits ($0.60), czyli stawkę edycji 4K high.
Lokalna edycja z maską
{
"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"
}
}
Maska musi mieć wymiary źródła i zawierać zarówno czarne (edycja), jak i białe (zachowaj) obszary. Z context_window: auto edytowany jest tylko obszar wokół maski w rozdzielczości źródła. Zbyt duża maska powoduje powrót do edycji całego obrazu.
Reguły walidacji pól
Waliduj po swojej stronie przed wysłaniem, aby błędne żądania odpadały od razu:
| Pole | Reguła |
|---|---|
model | ideogram-v4.6 lub ideogram-v4.6-edit |
prompt | Wymagane, od 1 do 10,000 znaków, nie same białe znaki |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 lub WIDTHxHEIGHT z małą literą x |
| Własny rozmiar | Każdy bok od 256 do 4096 i wielokrotność 32; proporcje w zakresie od 1:6 do 6:1 |
quality | very_low tylko gdy wynik ma najwyżej 4,194,304 pikseli |
n | Liczba całkowita od 1 do 8; ciągi znaków i wartości logiczne są odrzucane |
image_urls | Tylko edycja; tablica z dokładnie jednym obrazem |
mask_url, edit_precision: high | Wymagają size: auto (lub braku size) |
background | Odrzucane, gdy edit_precision ma wartość high |
context_window: auto | Wymaga mask_url i edit_precision: high |
| Nieznane pola | Odrzucane z błędem unsupported fields |
Przykłady: 2304x3072 przechodzi (oba boki to wielokrotności 32); 1296x3168 nie przechodzi, bo 1296 nie jest wielokrotnością 32, choć Ideogram 4.5 go akceptował; 4096x512 nie przechodzi (proporcje 8:1); very_low przy 2048x3072 nie przechodzi.
Błędy, które warto obsłużyć
code | Znaczenie | Co zrobić |
|---|---|---|
| 400 | Nieprawidłowe parametry | Popraw ciało; nie ponawiaj bez zmian |
| 401 | Brak klucza API lub nieprawidłowy klucz | Sprawdź nagłówek Authorization: Bearer |
| 402 | Niewystarczające kredyty | Doładuj konto i wyślij ponownie |
| 429 | Przekroczony limit żądań | Odczekaj i ponów później |
| 500, 502, 503 | Błąd serwera, dostawcy upstream lub dostępności | Ponów z backoffem; najpierw sprawdź, czy ID zadania nie zostało już zwrócone |
Zadanie, które dotrze do failed, podaje przyczynę w error_message. Pełną listę znajdziesz w Error Codes.
Użyj callbacku zamiast odpytywania
Dodaj "callback_url": "https://your-app.example.com/poyo-webhook" na najwyższym poziomie ciała, a nie wewnątrz input. Gdy zadanie się zakończy lub nie powiedzie, PoYo wyśle POST z danymi zadania na ten URL, podpisany HMAC-SHA256 w nagłówku X-Webhook-Signature; regułę podpisu opisuje dokumentacja webhooków. Zostaw powolne odpytywanie jako zapas na callbacki, które nigdy nie dotrą.
Jak liczony jest Twój pierwszy rachunek
Ideogram 4.6 API rozlicza każdy obraz wyjściowy: cena progu jakości i rozmiaru × n. 1 credit = $0.005.
| Żądanie | Próg | Opłata |
|---|---|---|
Domyślne (auto, medium, n: 1) | Tekst-na-obraz medium 2K | 12 credits ($0.06) |
very_low, 3:4, n: 1 | Tekst-na-obraz very_low 2K | 1.6 credits ($0.008) |
high, 1728x2304, n: 2 | Tekst-na-obraz high 2K | 40 credits ($0.20) |
high, 2304x3072, n: 1 | Tekst-na-obraz high 4K | 40 credits ($0.20) |
Edycja wysokiej precyzji źródła 2304×3072, high | Edycja high 4K | 120 credits ($0.60) |
Wiersze very_low i 2304x3072 zgadzają się z tym, co pobrano za nasze zadania z dnia premiery. Przy edycjach z size: auto cena jest wyceniana na podstawie rozmiaru obrazu źródłowego i rozliczana według dostarczonego obrazu, nigdy powyżej wyceny. Artykuł o cenach zawiera więcej przeliczonych przykładów.
Najczęściej zadawane pytania
Czy Ideogram 4.6 API jest zgodne z OpenAI SDK?
Nie. To asynchroniczne API zadań: wyślij żądanie do /api/generate/submit, a następnie odpytuj /api/generate/status/{task_id} albo odbierz callback. Wystarczą zwykłe requests, fetch lub cURL.
Jak edytować obraz przez Ideogram 4.6 API?
Wywołaj ideogram-v4.6-edit z jednym URL w image_urls i opisem zmiany w prompt. Dodaj edit_precision: high, aby zachować piksele, których nie prosiłeś zmieniać.
Czy mogę wysyłać obrazy referencyjne do ideogram-v4.6?
Nie. W PoYo referencje trafiają do reference_image_urls w ideogram-v4.6-edit, do 4 lub 3 z maską.
Ile obrazów zwraca jedno żądanie do Ideogram 4.6 API?
Od 1 do 8, ustawiane przez n. Każdy obraz jest rozliczany według ceny progu.
Dlaczego moje żądanie do Ideogram 4.6 API zostało odrzucone z powodu rozmiaru?
Własne boki muszą być wielokrotnościami 32 w zakresie od 256 do 4096, a maski i edycje wysokiej precyzji wymagają size: auto.