Przewodnik migracji
Dwie platformy mogą oferować to samo zadanie i mimo to różnić się nazwami pól, wartościami domyślnymi, stanami końcowymi, znaczeniem błędów i tym, czym jest jedna jednostka rozliczeniowa. Migracja, która zaczyna się od bazowego adresu, znajduje to wszystko na produkcji.
Wyzwanie
Model to ta część, która przenosi się czysto. Nie przenosi się wszystko wokół niego: które pola są wymagane, jakie są wartości domyślne, jak trafia do środka obraz referencyjny, kiedy blokowane są pieniądze i co twój kod ma zrobić ze stanem, którego nigdy nie widział.
01
Spisz mapowanie osobno dla każdego endpointu, zamiast go zgadywać. Wejście jest walidowane według opublikowanego schematu przy zamkniętym additionalProperties, więc niezmapowane pole to 400 przy pierwszym prawdziwym żądaniu, a nie ostrzeżenie w logu.
02
createTask blokuje wycenę i zwraca ją jako cost z settled: false. Jeśli obecna platforma nalicza tylko przy powodzeniu, rozliczenia muszą zrozumieć blokady, zanim przeniesiesz jakikolwiek ruch.
03
Dziewięć wartości pokrywa każdą awarię, a content_rejected jest jedną z nich: odmowa to zakończone zadanie, a nie wyjątek. Odwzoruj swoje gałęzie obsługi błędów na tych dziewięciu przed przełączeniem, a nie po.
Podejście
Weź jeden przepływ, zapisz jego obecne wejścia, wyniki, awarie i koszt jednostkowy, a potem odtwórz te same warunki tutaj. Porównaj wycenę z jobs/quote z tym, co płacisz dziś, trzymaj obie ścieżki żywe za flagą i zwiększaj udział tylko dopóty, dopóki liczby się trzymają.
Najpierw wycena: przechodzi tę samą walidację i te same kontrole przy przyjęciu co utworzenie, nie blokując środków ani nie uruchamiając pracy.
POST /api/v1/jobs/quote
{
"model": "<publisher>/<model>/text-to-video",
"input": {
"prompt": "A slow aerial drift over a misty pine forest at sunrise",
"duration_seconds": 5,
"resolution": "1080p"
}
}200 OK — nothing reserved, nothing started
{
"code": 200,
"msg": "success",
"request_id": "req_example_quote",
"data": {
"quoteId": "qte_01k3m8x9q2z4v7n5p6r8s0t1w3",
"model": "<publisher>/<model>/text-to-video",
"estimatedCost": "0.750000",
"maxCharge": "0.750000",
"currency": "USD",
"quantity": "5",
"unit": "second",
"expiresAt": "2026-09-12T12:05:00Z"
}
}Kontrakt
| Pole lub nagłówek | Wartość lub limit |
|---|---|
| POST /api/v1/jobs/quote | no hold · signed quote valid 5 min |
| quoteId + expectedCost | 40901 when the price moved |
| 402 | 40201 balance · 40202 spend cap |
| published call name | immutable · renames keep a 308 |
Przesuń w poziomie, żeby zobaczyć wszystkie kolumny.
Integracja
Dopasowanie
Dowody
POST /api/v1/jobs/quote przechodzi tę samą walidację i te same kontrole przy przyjęciu co utworzenie, zwraca estimatedCost, maxCharge, quantity i unit, i niczego nie blokuje. Podpisana wycena jest ważna pięć minut.
Wyślij quoteId i expectedCost razem z utworzeniem. Jeśli cena w międzyczasie się zmieniła, przyjęcie zwraca kod aplikacyjny 40901, zanim cokolwiek zostanie zablokowane.
Wydana nazwa wywołania pozostaje ważna, a zmiana nazwy zostawia po sobie 308 i alias. Twoja tabela mapowania nie gnije po cichu między wydaniami.
Przed startem
FAQ
Modele
Każdy odnośnik prowadzi na stronę danej rodziny modeli: wejścia, limity, zasady dotyczące treści i aktualna cena za jednostkę.
Co dalej
Przenoś po jednym przepływie: zmapuj pola, ujednolić stany i błędy, porównaj rachunek i przełącz ruch z wycofaniem, które przetestowano.
Źródło: fal model APIs ↗