GPT Image 2 / 2.5: generowanie i edycja obrazów

Wybierz endpoint przed napisaniem zapytania: text-to-image używa /images/generations; image-to-image używa /images/edits z przesłanymi plikami obrazów. Wzmianka o „obrazie referencyjnym 1” w promptcie nie dołącza obrazu.

Modele i endpointy

Identyfikator modelu	Text-to-image	Image-to-image
gpt-image-2	/images/generations	/images/edits + pliki obrazów
gpt-image-2.5-sunburst	/images/generations	/images/edits + pliki obrazów
gpt-image-2.5-flare	/images/generations	/images/edits + pliki obrazów

To są różne identyfikatory modeli. Przy zmianie modelu zmień jawnie model; GPT Image 2.5 nie jest aliasem GPT Image 2. Sprawdź aktualną dostępność i cennik konta w marketplace.

Operacja	Metoda i endpoint	Format zapytania
Text-to-image	POST https://apimaster.ai/v1/images/generations	JSON
Image-to-image / edycja	POST https://apimaster.ai/v1/images/edits	multipart/form-data z rzeczywistymi plikami obrazów
Asynchroniczna edycja obrazu	POST https://apimaster.ai/v1/images/edits/async	Te same pliki multipart co dla edycji; zwraca identyfikator zadania
Asynchroniczny text-to-image	POST https://apimaster.ai/v1/images/generations/async	JSON; zwraca identyfikator zadania
Odpytanie zadania	GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID	Uwierzytelnianie Bearer

Aby uzyskać odpowiedź zadania z edycji obrazu, użyj /images/edits/async. Prześlij te same pliki i pola co przy edycji synchronicznej, a następnie odpytuj /tasks/{task_id}. Nie przenoś zapytania o edycję do generations/async. Te endpointy zadań korzystają z istniejącego kontraktu asynchronicznego: asynchroniczny dostawca może niezwłocznie zwrócić swoje zadanie, podczas gdy dostawca synchroniczny może zakończyć edycję, zanim brama zwróci identyfikator zadania. Nie jest to obietnica natychmiastowego wykonania w tle. Nie używaj Chat Completions dla tych modeli.

Uwierzytelnianie i limity czasu

Utwórz klucz API i wysyłaj Authorization: Bearer YOUR_API_KEY. Zapytania generowania JSON używają Content-Type: application/json. Przy przesyłaniu plików pozwól, by cURL lub Twoja biblioteka HTTP wygenerowała granicę multipart; nie ustawiaj ręcznie nagłówka Content-Type.

Zezwól na co najmniej 180 sekund dla podstawowych zapytań, 300 sekund dla wyższej rozdzielczości i 600 sekund dla wymagających edycji lub wysokiej jakości. Limit czasu klienta nie dowodzi, że zapytanie do dostawcy zostało przerwane. Unikaj natychmiastowego ponownego wysyłania duplikatów.

Text-to-image: generowanie JSON

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Dla Sunburst lub Flare zastąp identyfikator modelu wartością gpt-image-2.5-sunburst lub gpt-image-2.5-flare. Nie dodawaj obrazów referencyjnych do tego przykładu; użyj poniższych przykładów edycji.

Image-to-image: przesyłanie jednego obrazu referencyjnego

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

Zastąp reference.png istniejącym lokalnym obrazem. @ mówi cURL, aby przesłał bajty pliku; image=reference.png wysyła tylko łańcuch z nazwą pliku. Ten wzorzec endpointu dotyczy także gpt-image-2 i gpt-image-2.5-sunburst.

Image-to-image: przesyłanie wielu obrazów referencyjnych

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Powtórz to samo pole image[] dla każdego pliku, w kolejności opisanej w prompcie. n to liczba obrazów wyjściowych, a nie liczba referencji. Limity referencji zależą od wybranego modelu i dostępnej trasy; nie zakładaj uniwersalnego limitu 16 obrazów. Zacznij od jednej referencji i n=1, a następnie dodawaj wejścia w miarę potrzeby.

Przykład edycji w Pythonie

Zainstaluj requests. Ten przykład przesyła rzeczywisty plik i obsługuje zarówno odpowiedzi z adresem URL, jak i base64.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

Dla wielu plików przekaż listę powtórzonych wpisów ("image[]", (filename, file_object, mime_type)) do files. Pozostaaw każdy plik otwartym do zakończenia zapytania.

Asynchroniczna edycja obrazu

Użyj tego endpointu z GPT Image 2, Sunburst lub Flare, gdy Twoja aplikacja korzysta z identyfikatorów zadań. Zasady przesyłania plików, kolejność referencji, limity możliwości i uwierzytelnianie są takie same jak przy edycji synchronicznej.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Zgłoszenie zwraca data[0].task_id. Odpytuj używając tego samego identyfikatora modelu:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

Zakończone śledzone zadanie ma taki kształt; zawiera każdy wygenerowany obraz:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

Zadanie należy do konta zgłaszającego. Odpytuj je ważnym kluczem API tego konta. Nieudane zgłoszenie zwraca błąd, a nie użyteczne zadanie; gdy identyfikator zadania został zwrócony, kontynuuj odpytywanie tego zadania zamiast ponownie zgłaszać edycję. Zobacz tabelę statusów odpytywania poniżej.

Istniejące integracje URL lub base64

Jeśli Twoje wejście to URL, pobierz obraz w swojej aplikacji i prześlij jego bajty do /images/edits. Jeśli to data URI base64, zdekoduj ładunek do pliku lub bufora bajtów i prześlij go. Nie wysyłaj URL ani tekstu base64 tak, jakby to było przesyłanie pliku.

Niektóre trasy GPT Image 2 obsługują rozszerzenie image_urls w generations. To nie jest przenośny kontrakt edycji obrazu i nie wolno zakładać, że działa z GPT Image 2.5. Nowe integracje powinny korzystać z powyższych przykładów edycji multipart. Zapytanie JSON zawierające image_urls, image lub images nie jest równoważne przesyłaniu plików do edits.

Parametry i limity możliwości

Pole	Zastosowanie
model	Wymagane; użyj jednego dokładnego identyfikatora modelu z powyższej tabeli
prompt	Wymagane; opisz wynik i kolejność referencji
image / image[]	Rzeczywiste przesyłane pliki dla edycji; użyj PNG lub JPEG w podstawowych przykładach
n	Liczba obrazów wyjściowych; zacznij od 1; maksimum zależy od trasy
size	Opcjonalne; 1024x1024 w podstawowym przykładzie; inne wymiary pikselowe lub proporcje zależą od trasy
resolution	Opcjonalne rozszerzenie zależne od trasy, takie jak 1k, 2k, 4k; nie każdy model/trasa obsługuje każdy poziom
quality	Opcjonalne; akceptowane wartości i koszt zależą od trasy
background, output_format, output_compression	Opcjonalne; przezroczystość i kodowanie wyjścia wymagają obsługi przez trasę
mask	Tylko GPT Image 2, gdy dostępna trasa edits obsługuje przesyłane maski; nieobsługiwane przez aktualny handler multipart GPT Image 2.5

Dla GPT Image 2 obsługę masek należy sprawdzić osobno od zwykłej edycji referencyjnej. Zgodna maska PNG musi odpowiadać wymiarom wejścia i zawierać kanał alfa. Aktualny endpoint multipart GPT Image 2.5 odrzuca przesyłane pliki masek; nie dodawaj maski do powyższych przykładów Sunburst ani Flare. Nie zakładaj, że obejście JSON mask_url jest obsługiwane bez sprawdzenia wybranej trasy.

Wysyłaj tylko opcjonalne pola, których potrzebujesz. Mogą one zmienić kwalifikujące się trasy i cenę; jawne ustawienie wartości domyślnej nie zawsze jest równoważne jej pominięciu. Żadna stała tabela rozmiarów pikselowych ani lista parametrów zaawansowanych nie ma zastosowania jednolicie do wszystkich trzech identyfikatorów modeli. Rzeczywiste ceny i obsługiwane możliwości wynikają z marketplace i odpowiedzi na zapytanie.

Odpowiedzi synchroniczne

Udane generowanie lub edycja zwraca wpisy obrazów w data:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

W zależności od trasy i formatu wyjścia wpis może zamiast tego zawierać b64_json. Zdekoduj go do bajtów obrazu. Pobieraj tymczasowe adresy URL wyników niezwłocznie. Odpowiedź HTTP 200 lub sama liczba obrazów nie dowodzi, że szczegóły referencji zostały zachowane; porównaj wynik z wejściem.

Zadania asynchroniczne: zgłoszenie i odpytywanie

Dla text-to-image wyślij JSON bez obrazów referencyjnych do generations/async. Dla edycji obrazu użyj powyższego przykładu multipart edits/async. Oba używają tego samego endpointu odpytywania zadań:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

Koperta zgłoszenia zwykle raportuje submitted; dostawca może już raportować stan zakończenia. Pierwsze odpytanie może już być zakończone. Identyfikator zadania nie gwarantuje natychmiastowej odpowiedzi: jeśli wybrany dostawca jest synchroniczny, platforma czeka na zakończenie generowania przed zwróceniem zadania. Ustaw wystarczający limit czasu zgłoszenia.

Odpytuj tym samym identyfikatorem modelu, którego użyto w zgłoszeniu:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Status zadania	Działanie
pending, submitted, processing, in_progress	Czekaj; odpytaj ponownie po 3–5 sekundach
succeeded, success, completed	Odczytaj każdy wpis w data.result.images; śledzone zadania używają łańcuchowego url, podczas gdy starsze odpowiedzi dostawców mogą używać tablicy URL
failed, error, cancelled	Przerwij odpytywanie i zbadaj błąd

Użyj skończonego ogólnego terminu odpytywania, na przykład 10 minut. Jeśli upłynie, zachowaj identyfikator zadania do późniejszego sprawdzenia, zamiast automatycznie tworzyć kolejne płatne zadanie. Odpowiedzi odpytywania zadań i synchroniczne odpowiedzi obrazów mają różne struktury.

Rozwiązywanie problemów z obrazami referencyjnymi

1. Zweryfikuj, że rzeczywista ścieżka zapytania to /v1/images/edits lub /v1/images/edits/async, a nie generations lub generations/async.
2. Zweryfikuj, że multipart zawiera bajty pliku pod image lub powtórzonym image[], z wygenerowaną granicą. Tekst promptu, nazwy plików i liczby referencji nie zastępują plików.
3. Sprawdź dokładny identyfikator modelu. Rozszerzenie GPT Image 2 nie jest automatycznie obsługiwane przez Sunburst ani Flare.
4. Jeśli szczegóły zadania/logów nie pokazują podglądu, nie wyciągaj wniosku, że żaden obraz nie został wysłany: logi mogą pomijać dane base64 i zawartość przesłanych plików. Odwrotnie, zalogowana liczba referencji nie dowodzi, że dostawca użył obrazów.
5. Przetestuj z prostą referencją zawierającą charakterystyczne napisy lub kształty i poproś o zmianę tła bez opisywania tych szczegółów. Porównaj wynik wizualnie.
6. W przypadku kontaktu z pomocą techniczną zachowaj identyfikator zapytania (X-Oneapi-Request-Id), identyfikator zadania, jeśli występuje, model, endpoint, znacznik czasu, zanonimizowane pola zapytania i obrazy referencyjne. Nigdy nie udostępniaj swojego klucza API.

Przy odpowiedzi 400 sprawdź kompatybilność endpointu i parametrów; 401 oznacza błąd uwierzytelniania; 429 oznacza limit szybkości lub limit przydziału. Przy limitach czasu lub awariach dostawcy zachowaj identyfikator zapytania/zadania i sprawdź istniejące zadanie lub rekord użycia przed ponownym wysłaniem.