Integracja produkcyjna

Przejdź przez tę stronę jak przez listę kontrolną, zanim na twojej integracji zaczną polegać prawdziwi użytkownicy albo prawdziwe pieniądze. Każda sekcja mówi, co zrobić, dlaczego to ważne i gdzie znaleźć szczegóły. Jeśli pierwsze wywołanie masz jeszcze przed sobą, zacznij od strony Przygotuj konto i szybkiego startu.

Wybierz model i protokół

• Wybierz model, który twój klucz naprawdę może wywołać. Wywołaj GET /api/v1/models ze swoim kluczem API i korzystaj tylko z modeli, w których zarówno enabled, jak i available mają wartość true. Z tej samej odpowiedzi odczytaj inputSchema modelu (listę przyjmowanych pól) oraz examples. Strona modelu w serwisie mówi, co model potrafi, ale nie dowodzi, że twój klucz może go wywołać w tej chwili. Zobacz Modele.
• Korzystaj z właściwego punktu wejścia. Zadania obrazu, wideo i innych mediów idą przez API zadań pod /api/v1 (createTask, a potem recordInfo albo callback). Modele tekstowe możesz też wywoływać klientami zgodnymi z OpenAI lub Anthropic pod /v1 albo klientami zgodnymi z Gemini pod /v1beta. Zobacz Tekst i streaming.
• Uwierzytelniaj się wyłącznie kluczem API. Plik cookie z logowania do konsoli nie jest poświadczeniem API i nigdy nie wolno kopiować go do kodu.

Chroń klucze i saldo

• Trzymaj klucz na swoim serwerze. Umieść go w zmiennej środowiskowej (SPICY_API_KEY) na backendzie – nigdy w kodzie przeglądarki, w aplikacji mobilnej ani w publicznym repozytorium. Zobacz Uwierzytelnianie.
• Osobny klucz dla każdego środowiska i każdej usługi. Nazwij każdy klucz po tym, co z niego korzysta (na przykład „production-worker”), żeby móc unieważnić jeden bez zatrzymywania pozostałych.
• Ustaw limity na kluczu produkcyjnym: limit dzienny na poziomie, który zniesiesz w wyjątkowo złym dniu, budżet miesięczny, dozwolone modele oraz – przy wywołaniach z serwera – listę dozwolonych IP. Zobacz ograniczenia pojedynczego klucza. Przy edycji klucza pamiętaj, że puste pole limitu oznacza brak limitu.
• Pilnuj dat wygaśnięcia. Klucz z datą wygaśnięcia przestaje działać z końcem tego dnia (UTC) i zwraca ten sam 401 co klucz unieważniony. Wpisz tę datę do kalendarza albo w ogóle jej nie ustawiaj dla backendu, który ma działać latami.
• Nie dopuść, żeby środki skończyły się w połowie serii. Zadanie odrzucone z powodu salda zwraca 40201 i nigdy nie trafia do kolejki. Włącz Alert o niskim saldzie w sekcji Powiadomienia i rozważ automatyczne doładowanie.
• Limity zespołu też obowiązują. Jeśli twój klucz należy do zespołu, dzienne i miesięczne limity zespołu mogą zatrzymywać zadania z kodem 40202, nawet gdy własne limity klucza nie zostały osiągnięte. Każde zadanie jest wtedy opłacane z salda właściciela zespołu. Zobacz Limity wydatków.
• Zaplanuj wymianę klucza podpisującego webhooki. Wymiana klucza w konsoli nie ma okresu przejściowego: stary klucz natychmiast przestaje podpisywać. Dostarczenia, które są jeszcze ponawiane, dostają podpis nowym kluczem. Wymieniaj klucz w spokojnym okresie, od razu wdróż nowy klucz w swoim odbiorniku, a wszystko, co przepadło w międzyczasie, odzyskaj przez recordInfo. Zobacz Webhooki.

Przygotuj dane wejściowe na serwerze

• Sprawdzaj dane względem aktualnego schematu. Trzymaj się typów pól, dozwolonych wartości i wymagań warunkowych z inputSchema, a po zmianie modelu sprawdź dane jeszcze raz – każdy model ma własny schemat.
• Przekazuj media w obsługiwany sposób. Użyj publicznie dostępnego adresu https:// albo obsługiwanego wejścia w Base64. Dla plików lokalnych poproś o adres do przesyłania, wyślij bajty metodą PUT, wywołaj files/{fileId}/commit, a zwrócony adres spicy:// wpisz w pole wejściowe modelu. Zobacz Media.
• Wykorzystaj każdy przesłany plik, zanim wygaśnie. Adres spicy:// działa do chwili expiresAt podanej w odpowiedzi na zatwierdzenie (domyślnie 1 dzień). Nie pobieraj hurtowo adresów do przesyłania, których potem nie użyjesz – niewykorzystane liczą się do limitu. Zobacz Limity żądań.

Wyceniaj, zanim przyjmiesz opłatę

• Pokaż cenę, zanim wydasz pieniądze. Wyślij kompletne model, input i callBackUrl na POST /api/v1/jobs/quote. Osobie, która płaci, pokaż estimatedCost, maxCharge, walutę (USD) i expiresAt. Wycena jest bezpłatna: nie tworzy zadania i nie blokuje środków.
• Wysyłaj dokładnie to, co zostało potwierdzone. Wycena jest ważna pięć minut. Po potwierdzeniu wyślij to samo żądanie do createTask, dodając quoteId i expectedCost.
• Obsłuż 40901. Ten kod oznacza, że od chwili wyceny wycena wygasła, dane wejściowe się zmieniły albo zmieniła się cena. Pobierz nową wycenę i pokaż nową kwotę; nigdy nie akceptuj po cichu wyższej. Zobacz Wyceny.
• Licz pieniądze dokładnie. Kwoty to liczby dziesiętne zapisane jako tekst, na przykład "0.008". Przechowuj je i dodawaj arytmetyką dziesiętną, a nie zmiennoprzecinkową. Zobacz Rozliczenia.

Zapisuj operację biznesową

To twoje własne zapisy pozwalają wrócić do porządku, gdy wywołanie sieciowe urwie się w połowie.

• Zapisz przed wysłaniem: własny identyfikator zamówienia lub operacji, krótki opis żądania bez sekretów i bez pełnych promptów (wystarczający, żeby je potem rozpoznać) oraz Idempotency-Key, który zamierzasz wysłać.
• Zapisz po przyjęciu: taskId i request_id z odpowiedzi.
• Używaj tego samego klucza dla tego samego zgłoszenia. W ciągu 24 godzin wyślij pierwotny Idempotency-Key ponownie z tego samego konta, tym samym kluczem API i z tym samym żądaniem; dostaniesz z powrotem pierwotne zadanie zamiast drugiej opłaty. Zobacz Idempotentność.
• Traktuj przekroczenie czasu jako „nie wiadomo”, a nie „nie powiodło się”. Zanim zdecydujesz się utworzyć nowe zadanie, odzyskaj pierwotne zgłoszenie jego kluczem. Zobacz Rozwiązywanie problemów.
• Wiedz, ile kosztuje ponowienie. Ponowienie zadania, które już się nie powiodło, tworzy nowe zadanie na aktualnych warunkach i po aktualnych cenach.

Niezawodnie obsługuj callbacki i wyniki

• Weryfikuj każdy callback. Zanim sparsujesz treść, sprawdź podpis i znacznik czasu względem oryginalnych bajtów żądania, a potem odfiltruj duplikaty i zapisz zdarzenie. Zobacz Webhooki.
• Potwierdzaj szybko. Od razu odpowiedz statusem 2xx, a powolną pracę wykonaj we własnej kolejce.
• Spodziewaj się duplikatów i opóźnień. O tym, co zrobić, decyduj na podstawie state zadania, a nie kolejności, w jakiej przychodzą callbacki.
• Zostaw odpytywanie jako plan awaryjny. Jeśli callback się spóźnia, odczytuj recordInfo z coraz dłuższymi przerwami, a nie co sekundę.
• Czytaj właściwy sygnał. HTTP 202 z createTask oznacza, że zadanie zostało przyjęte. state: "succeeded" oznacza, że generacja się zakończyła. settled: true oznacza, że opłata jest ostateczna.

Ogranicz współbieżność i zachowuj wyniki

• Ogranicz liczbę trwających zadań na konto i wyznaczaj własnym żądaniom terminy. Każde przyjęte zadanie blokuje środki aż do rozliczenia.
• Przy 429 stosuj się do Retry-After i unikaj sytuacji, w której wielu klientów odpytuje co sekundę w tym samym rytmie. Zobacz Limity żądań.
• Buforuj dane katalogu krótko i prywatnie i nigdy nie traktuj wyceny jak stałego cennika.
• Archiwizuj wyniki, które chcesz zachować. Linki do pobrania działają 20 minut; wygenerowane media przechowujemy najwyżej około 14 dni, a przesłane pliki – jeden dzień. Możesz te okresy skrócić albo wcześniej usunąć treść zadania przez POST /api/v1/jobs/purge. Skrócenie okresu przechowywania może też usunąć wyniki zadań wykonanych już wcześniej – zobacz Przechowywanie i usuwanie danych.
• Nie licz na to, że rozłączenie zatrzyma pracę. Przyjęte zadanie działa dalej i nie da się go anulować.

Sprawdź przed uruchomieniem

Zacznij od bezpłatnych wywołań: katalogu (GET /api/v1/models), salda (GET /api/v1/chat/credit) i wyceny. Potem przepuść jedną małą, prawdziwą generację przez własny proces potwierdzania kosztu – jest rozliczana jak każde inne zadanie. Sprawdź, czy twoja integracja radzi sobie z każdą z tych sytuacji:

Zapisuj w logach request_id, taskId, czas, state i kwoty. Klucze API i pełne prompty trzymaj z dala od ogólnych logów.

Powiązane strony

Wyceny i zgodność protokołów · Katalog modeli i schematy · Media · Webhooki · Błędy · Rozwiązywanie problemów i odzyskiwanie · Rozliczenia · Przechowywanie i usuwanie danych