Migracja API obrazów do SeedRouter: żądania i zadania

Migracja API obrazów do SeedRouter wymaga sprawdzenia kontraktu żądania i odpowiedzi, a nie tylko podmiany klucza API i adresu bazowego. GPT Image 2 korzysta ze znanych pól generowania obrazów, ale wysłanie żądania zwraca identyfikator zadania. Aplikacja musi zapisać ten identyfikator, odpytywać zadanie do zakończenia i odczytać adresy gotowych obrazów.

Najmniejsza użyteczna migracja to jedno żądanie z tekstu na obraz wysłane z kodu po stronie serwera. Doprowadź je do działania, zanim przeniesiesz edycje z referencją, maski albo większą partię. Zostaw dotychczasową integrację dostępną, dopóki nowa ścieżka nie przejdzie tych samych testów odbiorczych.

Które założenia trzeba zmienić?

Znajdź kod, który zamienia żądanie obrazu w użyteczny plik. Może dziś oczekiwać obrazu w pierwszej odpowiedzi, dekodować pole base64 albo wysyłać plik jako multipart. Każde z tych założeń trzeba osobno zestawić z dokumentacją GPT Image 2 w SeedRouter.

Dotychczasowe założenie	Kontrakt SeedRouter	Zmiana w aplikacji
Wysłanie zwraca gotowy obraz	Wysłanie zwraca odniesienie do zadania	Zapisz `id`, zanim zaczniesz czekać na wynik
Wynik jest w tablicy `data` odpowiedzi na wysłanie	Obrazy ukończonego zadania są w `output.data`	Odczytuj wyniki po zakończeniu zadania
Klient dekoduje `b64_json`	Obrazy wracają jako hostowane adresy URL	Pobierz zwrócone adresy URL
Edycja wysyła bajty pliku	Referencje używają obiektów URL w `images`	Udostępnij obrazy wejściowe pod adresem URL
Osobna ścieżka edycji wybiera tryb edycji	Operację wybierają `images` i `mask`	Korzystaj z publicznego endpointu generowania
Limit czasu po stronie klienta oznacza błąd	Zadanie może nadal być przetwarzane	Wróć do odpytywania zapisanego identyfikatora

Dlatego synchroniczne wywołanie SDK do obrazów nie jest zamiennikiem jeden do jednego, nawet jeśli przyjmuje konfigurowalny adres bazowy. Zachowaj te ustawienia modelu, których nadal potrzebujesz, ale przerób kod aplikacji, który czeka na wynik i go przetwarza.

Zmapuj pola żądania, zanim ruszysz kod

Zacznij od model, prompt, size, quality i n. Jako identyfikatora modelu użyj gpt-image-2. Wysyłaj jawne wymiary, na przykład 1024x1024, albo auto; nie przenoś osobnego pola resolution ani nie podstawiaj proporcji kadru w miejsce rozmiaru.

Dokument OpenAPI SeedRouter warto mieć otwarty przy tym przeglądzie. Porównuj pola, które aplikacja naprawdę wysyła, łącznie z wartościami dokładanymi przez SDK, zamiast sprawdzać tylko argumenty widoczne w miejscu wywołania. Nieznane pola są odrzucane.

W tym modelu style, response_format i konfigurowalne input_fidelity nie są akceptowanymi polami żądania. Usuń te założenia, zamiast chować je w ogólnym obiekcie opcji. Żądanie nie obsługuje też stream ani partial_images; postęp w tej integracji sygnalizuje status zadania.

Ustawienia wyjścia mają zależności. Jeśli prosisz o przezroczystość, wybierz PNG. output_compression wysyłaj wyłącznie dla JPEG, nigdy dla PNG. Zerowa wartość kompresji jest poprawna, więc unikaj sprawdzania „czy wartość jest prawdziwa” i podmieniania jej na domyślną. To drobiazgi, których udane podstawowe żądanie nie sprawdzi.

Porzuć założenie o odpowiedzi synchronicznej

Poniższy przykład w Node.js wysyła jedno żądanie i wypisuje identyfikator zadania. Ustaw SEEDROUTER_API_KEY na serwerze; nigdy nie umieszczaj klucza w kodzie przeglądarki ani w publicznej zmiennej środowiskowej.

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',
    prompt: 'A cobalt-blue ceramic mug on a pale gray tabletop.',
    size: '1024x1024',
    quality: 'low',
    n: 1,
  }),
  signal: AbortSignal.timeout(60000),
});
const task = await response.json();
if (!response.ok) {
  // Preserve a task reference if one accompanies an uncertain submission.
  if (typeof task.id === 'string') console.log('Task reference:', task.id);
  throw new Error(`Submission needs review: HTTP ${response.status}`);
}
if (typeof task.id !== 'string' || !task.id) throw new Error('Missing task ID.');
console.log(task.id); // Persist this ID with your application's image record.

Do ręcznego testu wystarczy wypisanie identyfikatora. W aplikacji zapisz go, zanim oddasz sterowanie użytkownikowi. Rekord obrazu może wtedy pozostać w stanie oczekiwania, gdy użytkownik przejdzie gdzie indziej, a późniejsze sprawdzenie odzyska wynik.

Postęp sprawdzaj przez GET https://api.seedrouter.ai/v1/tasks/{id} z tym samym nagłówkiem autoryzacji. Przy completed odczytaj output.data[].url. Przy failed obsłuż udokumentowany błąd i pokaż odpowiedni stan niepowodzenia. Gotowy do uruchomienia przykład z zapisem postępu znajdziesz we wsadowym wysyłaniu i odpytywaniu.

Nie dołączaj klucza API do żądania pobrania obrazu. Autoryzacja należy do wywołania API zadań, a nie do osobnego pobrania pliku spod zwróconego adresu.

Przenieś referencje i maski na wejścia URL

Dotychczasowy proces oparty na plikach lokalnych wymaga dodatkowego kroku: udostępnij obraz referencyjny pod dostępnym adresem HTTP(S), który kontrolujesz. Przekaż go jako images: [{"image_url": "https://example.com/reference.png"}], zastępując ten adres własnym. Nie wysyłaj ścieżki do pliku, adresu blob:, data URL w base64 ani identyfikatora Files ID.

Sprawdź, czy adres działa bez ciasteczek logowania z twojej przeglądarki. Adres, który otwiera się wyłącznie w twojej zalogowanej sesji, nie nadaje się na referencję dla tego żądania. Utrzymuj obraz dostępny, dopóki zadanie jest przetwarzane; nie odbieraj dostępu zaraz po wysłaniu.

Maska ma postać mask: {"image_url": "https://example.com/mask.png"} i wymaga obrazów referencyjnych. Musi mieć takie same wymiary jak pierwszy obraz referencyjny. Zanim przeniesiesz istniejący proces edycji, przejrzyj wszystkie ograniczenia wejść multimedialnych, zwłaszcza formaty i rozmiary plików.

Co powinien obejmować test odbiorczy migracji?

Sprawdź zachowanie, na którym opiera się aplikacja, łącznie z przerwaniem pracy. Jeden udany obraz dowodzi tylko tego, że jedno żądanie zadziałało. Nie dowodzi, że stan oczekiwania przetrwa odświeżenie strony ani że nieudane pobranie nie doprowadzi do zduplikowanej generacji.

Wyślij żądanie z samym tekstem i zapisz zwrócony identyfikator przed rozpoczęciem odpytywania.
Przerwij odpytywanie, wznów je z tym samym identyfikatorem i sprawdź, że nie pojawia się dodatkowy POST.
Obsłuż processing, completed i failed jako odrębne stany.
Pobierz ukończony obraz bez wysyłania nagłówka autoryzacji API.
Sprawdź edycję z referencją pod dostępnym adresem, a potem obsługę błędu przy adresie niedostępnym.
Zweryfikuj pola opcjonalne, w tym zerową kompresję, według opublikowanego schematu.
Potwierdź, że obciążenia konta odczytujesz z historii użycia, a nie z wymyślonego pola kosztu w odpowiedzi zadania.

Do powtarzalnych testów błędów i przekroczeń czasu używaj odpowiedzi atrapowych. Mały, świadomy test na żywo zrób dopiero po przejściu tych kontroli; prawdziwe generacje zużywają saldo. Jeśli wynik wysłania jest niepewny, zbadaj sprawę, zanim spróbujesz ponownie. Lokalny wyjątek nie dowodzi, że żadne zadanie nie zostało przyjęte.

Najczęstsze pytania

Czy mogę zostawić dotychczasowe prompty?

Tak, jako punkt wyjścia, o ile mieszczą się w ograniczeniach żądania. Zachowaj kilka reprezentatywnych promptów do porównań, ale nie oczekuj identycznych obrazów przy powtórzonych generacjach.

Czy potrzebuję nowej biblioteki klienckiej?

Do przykładów z tego tekstu nie. Wystarczą zwykłe żądania HTTP. Jakikolwiek klient wybierzesz, musi obsłużyć wysłanie zadania i odpytywanie, zamiast oczekiwać gotowego obrazu od razu.

Gdzie znajdę końcowy koszt?

W historii użycia konta. Ukończone zadanie może zawierać zużycie tokenów, ale jego publiczna odpowiedź nie ma pola z kosztem. Szacowaniem zajmuje się przewodnik po cenach.

Dokończ migrację na granicy aplikacji

Migracja API obrazów jest ukończona, gdy aplikacja obsługuje cały cykl życia wyniku: przyjęte zadanie, stan oczekiwania, gotowy wynik, pobranie i błąd. Pierwszą zmianę zrób małą, przetestuj przypadki przerwania, a pozostałe żądania przenoś dopiero po sprawdzeniu ich założeń wejścia i wyjścia.

Przenieś integrację obrazów do SeedRouter