GPT Image 2.5 API w Pythonie: działający przykład

Aby wywołać GPT Image 2.5 API, wyślij żądanie POST na https://api.seedrouter.ai/v1/images/generations z ID modelu, takim jak gpt-image-2.5-flare, i promptem, zachowaj id zadania z odpowiedzi i odpytuj GET /v1/tasks/{id}, aż status będzie completed. Ukończone zadanie zawiera adresy URL twoich obrazów. Ten sam punkt końcowy obsługuje generowanie z tekstu, edycje z referencjami i edycje z maską.

Ten poradnik to kompletna, gotowa do uruchomienia ścieżka w Pythonie z odpowiednikiem w JavaScripcie, a po niej błędy, na które ludzie trafiają najczęściej, i co każdy z nich oznacza.

Czego potrzebujesz przed pierwszym żądaniem?

Dwóch rzeczy: klucza API i ID modelu.

Utwórz klucz na stronie kluczy API i trzymaj go w zmiennej środowiskowej na swoim serwerze, nigdy w kodzie przeglądarki:

export SEEDROUTER_API_KEY="your-key"

Następnie wybierz jedno z czterech ID modeli GPT Image 2.5. Kopiuj je dokładnie; nie ma samego ID gpt-image-2.5.

Jeśli nie wiesz, od którego modelu zacząć, użyj Flare; Flare vs Sunburst wyjaśnia, kiedy Sunburst jest tego wart.

Jak wygenerować obraz w Pythonie?

Wysłanie wraca natychmiast. Odpowiedź to odwołanie do zadania, a nie obraz.

import os
import requests

response = requests.post(
    "https://api.seedrouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "An amber glass bottle on a cream background, studio lighting",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

Zapisz task_id, zanim zrobisz cokolwiek innego. To jedyny uchwyt do pracy, za którą właśnie zapłaciłeś, i dzięki niemu odzyskasz wynik, jeśli twój proces zrestartuje się w trakcie renderowania obrazu.

Jak odebrać obraz?

Odpytuj zadanie co kilka sekund, aż się zakończy. Ta pętla czeka do dziesięciu minut; osiągnięcie tego limitu zatrzymuje twoją pętlę, a nie zadanie.

import time

print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Pobierz adresy URL, które chcesz zachować, i przechowuj je samodzielnie. Adresy URL wyników służą do przekazania wyniku, a nie do długoterminowego przechowywania.

Jak wygląda to samo wywołanie w JavaScripcie?

Żądanie jest identyczne; zmienia się tylko klient HTTP. Uruchamiaj je na swoim serwerze, żeby klucz nigdy nie trafił do przeglądarki.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2.5-flare',
    prompt: 'An amber glass bottle on a cream background, studio lighting',
    size: '1024x1024',
    quality: 'low',
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();

Odpytuj GET https://api.seedrouter.ai/v1/tasks/${taskId} z tym samym nagłówkiem, dokładnie jak w pętli w Pythonie.

Jak edytować istniejący obraz?

Dodaj obrazy referencyjne do tego samego żądania. Nie ma osobnego punktu końcowego do edycji ani pola trybu: wysłanie images czyni z żądania edycję, a dodanie mask ogranicza zmianę do jednego obszaru.

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Make the bottle blue. Preserve the composition and lighting.",
  "images": [{"image_url": "https://example.com/reference.png"}],
  "mask": {"image_url": "https://example.com/mask.png"}
}

Wejścia muszą być publicznymi adresami URL HTTPS. Możesz wysłać do 16 obrazów referencyjnych w formacie PNG, JPEG lub WebP, każdy poniżej 50 MB. Maska to plik PNG poniżej 4 MB o tym samym rozmiarze co pierwszy obraz referencyjny, a jej przezroczysty obszar oznacza, co zmienić. Ciągi base64, adresy data: i przesyłanie plików są odrzucane, więc najpierw prześlij pliki do własnego magazynu i wyślij adresy URL.

Dlaczego API zgłasza, że model jest niedostępny?

Kod błędu 20002 z HTTP 400 („The requested model is not available.”) oznacza, że wartość model nie jest ID, które API obsługuje. Zwykłą przyczyną jest drobna pomyłka: gpt-image-2.5 bez wariantu, gpt-image-2-5-flare z myślnikiem zamiast kropki albo literówka w sunburst. Skopiuj ID z tabeli powyżej.

Błędy parametrów są zgłaszane przed sprawdzeniem modelu. Jeśli żądanie ma też nieprawidłowe pole, dostajesz 20001 z komunikatem wskazującym to pole, na przykład quality. Najpierw popraw je; błąd modelu pojawi się przy następnej próbie, jeśli ID nadal jest błędne.

Zadanie może też zakończyć się niepowodzeniem po przyjęciu. Takie zapytanie nadal zwraca HTTP 200, ze status: "failed" i obiektem error, na przykład z kodem 60001 (zasady treści) lub 60002 (generowanie nieudane). Nieudane zadania nie są rozliczane. Katalog błędów wymienia każdy kod, w tym błędy salda i limitu żądań, wraz z kolejnym krokiem dla każdego.

Najczęściej zadawane pytania

Czy istnieje oficjalne wywołanie Python SDK, które zwraca obraz bezpośrednio?

Nie w tym API. Dostarczanie jest asynchroniczne: zawsze wysyłasz, zachowujesz identyfikator zadania i odpytujesz. stream i partial_images nie są obsługiwane.

Czy mogę zamówić kilka obrazów naraz?

Tak. Ustaw n od 1 do 10. Ukończone zadanie zawiera jeden adres URL na każdy dostarczony obraz, a rozliczane są dostarczone obrazy.

Jak uzyskać przezroczysty PNG?

Ustaw background na transparent, a output_format na png. JPEG nie ma kanału alfa, więc takie połączenie jest odrzucane przed uruchomieniem.

Zbuduj integrację wokół identyfikatora zadania

Zapisz identyfikator zadania w chwili, gdy go otrzymasz, odpytuj z limitem czasu i traktuj przekroczenie limitu odpytywania jako „nadal trwa”, a nie „nie powiodło się”. Wszystko inne, w tym każde pole i limit, znajdziesz w dokumentacji GPT Image 2.5 API, a żądanie bez kodu wypróbujesz w Playgroundzie.