how-tos

Ideogram 4.6 API – poradnik: pierwszy obraz i edycja w cURL i Pythonie

Poyo.ai Team
8 min read
Share:

Poradnik Ideogram 4.6 API z cURL i Pythonem

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:

PoleReguła
modelideogram-v4.6 lub ideogram-v4.6-edit
promptWymagane, od 1 do 10,000 znaków, nie same białe znaki
sizeauto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 lub WIDTHxHEIGHT z małą literą x
Własny rozmiarKażdy bok od 256 do 4096 i wielokrotność 32; proporcje w zakresie od 1:6 do 6:1
qualityvery_low tylko gdy wynik ma najwyżej 4,194,304 pikseli
nLiczba całkowita od 1 do 8; ciągi znaków i wartości logiczne są odrzucane
image_urlsTylko edycja; tablica z dokładnie jednym obrazem
mask_url, edit_precision: highWymagają size: auto (lub braku size)
backgroundOdrzucane, gdy edit_precision ma wartość high
context_window: autoWymaga mask_url i edit_precision: high
Nieznane polaOdrzucane 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ć

codeZnaczenieCo zrobić
400Nieprawidłowe parametryPopraw ciało; nie ponawiaj bez zmian
401Brak klucza API lub nieprawidłowy kluczSprawdź nagłówek Authorization: Bearer
402Niewystarczające kredytyDoładuj konto i wyślij ponownie
429Przekroczony limit żądańOdczekaj i ponów później
500, 502, 503Błąd serwera, dostawcy upstream lub dostępnościPonó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.

ŻądaniePrógOpłata
Domyślne (auto, medium, n: 1)Tekst-na-obraz medium 2K12 credits ($0.06)
very_low, 3:4, n: 1Tekst-na-obraz very_low 2K1.6 credits ($0.008)
high, 1728x2304, n: 2Tekst-na-obraz high 2K40 credits ($0.20)
high, 2304x3072, n: 1Tekst-na-obraz high 4K40 credits ($0.20)
Edycja wysokiej precyzji źródła 2304×3072, highEdycja high 4K120 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.

Share: