Rozwiązanie API wideo
Wideo jest w większości produktów najdroższą i najwolniejszą rzeczą do wygenerowania. Obie te liczby ustalają trzy pola w treści żądania, a zadanie pracuje dalej długo po tym, jak żądanie, które je uruchomiło, zdążyło zniknąć.
Wyzwanie
Żądanie wideo to nie jest wolniejsze żądanie obrazu. Długość, rozdzielczość i przełącznik dźwięku ustalają, ile zapłacisz i ile poczekasz – i robią to, zanim powstanie choćby jedna klatka.
01
Większość endpointów wideo nalicza opłatę za sekundę wyniku w wybranej rozdzielczości. Zmiana duration_seconds z 5 na 10 mniej więcej podwaja kwotę, a jeden stopień rozdzielczości podwaja ją ponownie. Oba pola są w schemacie endpointu oznaczone jako wpływające na cenę, więc wycena należy się obok samego suwaka, a nie na fakturze.
02
Tam, gdzie istnieje generate_audio, jest to wartość logiczna przenosząca żądanie na inną stawkę. Formularz, który ją ukrywa, po cichu wysyła droższą wersję każdego żądania.
03
createTask odpowiada 202 Accepted i zwraca taskId w stanie queued. Generowanie trwa po stronie serwera przez kolejne minuty. Wszystko, co czeka na pierwotnym gnieździe, kończy się timeoutem, a zadanie i opłata idą dalej.
Podejście
Wyceń dokładną treść przez POST /api/v1/jobs/quote, pokaż zwróconą kwotę, a potem wyślij tę samą treść do createTask razem z quoteId, expectedCost i zapisanym nagłówkiem Idempotency-Key. Cena, która zmieniła się między tymi dwoma wywołaniami, kończy się kodem aplikacyjnym 40901, zamiast pojawić się później jako niespodzianka.
Jedno wywołanie tworzące niesie model, zwalidowane wejście i opcjonalne wywołanie zwrotne. HTTP 202 znaczy przyjęte, a nie ukończone.
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/text-to-video",
"input": {
"prompt": "A slow aerial drift over a misty pine forest at sunrise",
"duration_seconds": 5,
"resolution": "1080p",
"generate_audio": true
},
"callBackUrl": "https://example.com/hooks/spicyapi"
}202 Accepted
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}Kontrakt
| Pole lub nagłówek | Wartość lub limit |
|---|---|
| POST /api/v1/jobs/createTask | 202 Accepted · state queued |
| duration_seconds · resolution · generate_audio | price-affecting fields |
| Idempotency-Key | 24 h · scoped to one API key |
| output.assets[].expiresAt | signed URL · results kept 14 days |
Przesuń w poziomie, żeby zobaczyć wszystkie kolumny.
Integracja
Dopasowanie
Dowody
Formularz na każdej stronie modelu powstaje z input_schema danego endpointu, a serwer waliduje według tego samego dokumentu. Pole, którego model nie deklaruje, kończy się kodem 400, a nie cichym pominięciem.
createTask blokuje wycenioną kwotę i zwraca ją jako cost z settled: false. Końcowa opłata nigdy nie przekracza blokady, a zadanie nieudane albo wygasłe zwalnia ją w całości.
Limit można ustawić dziennie, miesięcznie i na cały okres życia klucza, można go zawęzić do wskazanych modeli i adresów IP, a każde żądanie zapisu przyjmuje ten sam klucz idempotentności.
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
Porównaj endpointy wideo pod kątem długości, rozdzielczości, dźwięku i ceny, a potem wyślij to samo żądanie z własnego serwera.
