Wyceny i zgodność protokołów

Wycena dokładnego żądania

Wycena podaje cenę jednego, dokładnie określonego żądania, zanim zapłacisz. Jest bezpłatna, nie tworzy zadania i nie rezerwuje środków. Potem wysyłasz to samo żądanie z dołączoną wyceną, dzięki czemu zostanie przyjęte wyłącznie po cenie, która została ci pokazana.

Polecenia poniżej są przeznaczone dla terminala w macOS lub Linuksie, z SPICY_API_KEY ustawionym tak jak w szybkim starcie. MODEL_ID_FROM_CATALOG to symbol zastępczy: wpisz w jego miejsce wartość model ze swojego katalogu na żywo (GET /api/v1/models), a każde pole input weź ze schematu tego modelu.

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" }
}

curl https://api.spicyapi.ai/api/v1/jobs/quote \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

{
  "code": 200,
  "msg": "success",
  "data": {
    "quoteId": "QUOTE_ID_FROM_RESPONSE",
    "model": "MODEL_ID_FROM_CATALOG",
    "estimatedCost": "0.008",
    "maxCharge": "0.008",
    "currency": "USD",
    "quantity": "1",
    "unit": "per_image",
    "expiresAt": "2026-09-17T10:05:00Z"
  },
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" },
  "quoteId": "QUOTE_ID_FROM_RESPONSE",
  "expectedCost": "0.008"
}

SPICY_IDEMPOTENCY_KEY="$(uuidgen)"   # jeden na każde nowe zadanie; użyj go ponownie tylko przy ponownym wysyłaniu tego samego żądania

curl https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  --data-binary @submit.json

POST /api/v1/jobs/stream, czyli natywny strumień tekstu, przyjmuje wycenę w ten sam sposób; zobacz Tekst i streaming.

Odzyskiwanie utraconej odpowiedzi

Jeśli zgłoszenie przekroczyło limit czasu albo połączenie zostało zerwane, nie wiesz, czy żądanie zostało przyjęte. Dla createTask, retry i POST /v1/videos:

1. Wyślij pierwotne żądanie ponownie z pierwotnym Idempotency-Key, tym samym kluczem API. Dostaniesz z powrotem pierwotne zadanie w jego bieżącym stanie i nie zapłacisz dwa razy.
2. Nie twórz kolejnego zadania z nowym kluczem idempotentności. Nowy klucz oznacza nową generację i nową opłatę.
3. Powtórzenie już przyjętego żądania pozostaje ważne także po wygaśnięciu wyceny. Wygaśnięcie blokuje przyjęcie, a nie zadanie, które to przyjęcie utworzyło.
4. 409 nie oznacza „nie utworzono”. Albo żądanie się zmieniło (to nowa porcja pracy, która wymaga nowego klucza idempotentności), albo zostało wysłane innym kluczem API z tego samego konta (wyślij je ponownie pierwotnym kluczem API). Zobacz Idempotentność.
5. Ostateczną opłatę odczytasz z cost i settled w recordInfo.

Wyceny w oficjalnych narzędziach

CLI i serwer MCP pobierają wycenę i pytają człowieka przed każdym płatnym wywołaniem, więc tego kroku nie musisz budować samodzielnie:

• CLI: spicyapi tasks quote wycenia żądanie; spicyapi tasks create wycenia je jeszcze raz, wypisuje kwotę i pyta, zanim utworzy zadanie. Zobacz Koszty, potwierdzenia i bezpieczeństwo.
• MCP: asystent może swobodnie pobierać wyceny, ale przed utworzeniem zadania pyta ciebie przez klienta AI, podając cenę. Zobacz Koszty, potwierdzenia i bezpieczeństwo.
• SDK: quoteTask zwraca wycenę; przekaż jej quoteId i estimatedCost do createTask albo run.

Zgodność dla tekstu i wideo

SpicyAPI obsługuje też formaty OpenAI, Anthropic i Google Gemini dla modeli tekstowych oraz format OpenAI Videos dla wideo. Pełna lista endpointów jest w spisie endpointów; żądania, strumienie i błędy dla każdego protokołu opisuje strona Tekst i streaming.

Adres bazowy. Format OpenAI używa https://api.spicyapi.ai/v1. SDK Anthropic i Google GenAI same dopisują /v1 albo /v1beta, więc ustaw w nich adres bazowy https://api.spicyapi.ai.

Poświadczenie. Jeden klucz API do wszystkich formatów, w nagłówku Authorization: Bearer. Przyjmowane są też nagłówek x-api-key, którego używa SDK Anthropic, i nagłówek x-goog-api-key, którego używa SDK Google GenAI. Parametr ?key= w adresie URL – nigdy.

Model. Wybierz dokładny model z katalogu na żywo. To, czy działają narzędzia, wiadomości z obrazami i opcje generowania, zależy od schematu tego modelu, a nie od wybranego protokołu.

Kształt odpowiedzi. Każdy protokół zwraca własną strukturę odpowiedzi, a nie platformową {code, msg, data, request_id}.

Pola rozumowania

Modele czatu, które udostępniają tekst rozumowania, mogą zwracać opcjonalny ciąg znaków w message.reasoning_content, a przy streamingu – w delta.reasoning_content. Gdy kontynuujesz rozmowę po wywołaniu narzędzia, możesz zachować ten tekst w odpowiedniej wiadomości asystenta, jeśli schemat modelu w katalogu na żywo na to pozwala.

usage.completion_tokens_details.reasoning_tokens opisuje część rozumowania, która jest już wliczona w completion_tokens; nie dodawaj jej drugi raz. Nie każdy model zwraca tekst rozumowania albo te szczegóły tokenów.

Dwa kształty, które warto znać przed budową

• Responses wymaga pełnej rozmowy w input. previous_response_id nie jest obsługiwane.
• Videos przyjmuje JSON z polami model, prompt, input_reference, seconds i size, które są mapowane na własne pola modelu. Zwrócone id wideo jest zarazem identyfikatorem zadania, który przyjmuje recordInfo. Endpoint z treścią wideo przekierowuje statusem HTTP 302 na krótko ważny, podpisany adres URL.

Przykład czatu ze streamingiem w oficjalnych klientach OpenAI, Anthropic i Google znajdziesz w sekcji Użyj oficjalnego SDK. CLI i serwer MCP wysyłają i śledzą zadania natywne; nie przesyłają strumieniowo tokenów czatu.