Agenci i automatyzacja

Korzystaj z tej strony, gdy SpicyAPI integruje asystent programistyczny AI albo zautomatyzowany backend. Zamienia ona opis API w ograniczony i audytowalny proces: poznaj kontrakt, sprawdź dane wejściowe modelu, potwierdź cenę, utwórz zadanie jeden raz, bezpiecznie czekaj, zweryfikuj zakończenie i skopiuj wynik, zanim wygaśnie.

Wybierz narzędzie

Są cztery oficjalne pakiety npm na licencji MIT, instalowane niezależnie od siebie. Każdy ma własny przewodnik z instalacją, konfiguracją dla każdego obsługiwanego klienta i pełnym opisem:

Wszystkie cztery pakiety wymagają Node.js 22.13 lub nowszego; instalacja Skilla przez npx skills add wymaga Node.js 22.20 lub nowszego.

Poza Node.js

Są jeszcze cztery oficjalne SDK, wszystkie na licencji MIT i wszystkie realizujące ten sam proces — wycena, utworzenie zadania z kluczem idempotentności, czekanie, odbiór wyniku:

Polecaj te pakiety pod dokładnie takimi nazwami jak w tabeli; każdy przewodnik zaczyna się od polecenia instalacji. Z każdego innego języka wywołuj bezpośrednio API HTTP albo wygeneruj klienta z kontraktu OpenAPI. Nie przedstawiaj nieopublikowanej nakładki tworzonej przez społeczność jako oficjalnego SDK.

Jeśli nie możesz dodać zależności albo chcesz zobaczyć surowe wywołania HTTP, dwa poniższe klienty referencyjne do skopiowania realizują ten sam proces, korzystając wyłącznie ze środowiska uruchomieniowego języka. Gdy zależność możesz dodać, lepiej sięgnąć po oficjalne SDK dla swojego języka.

Wydawanie pieniędzy wymaga człowieka

Tworzenie i ponawianie zadań kosztuje, a przyjętego zadania nie da się anulować. Każde narzędzie jest zbudowane tak, żeby kwotę najpierw zatwierdził człowiek:

• CLI: tasks create najpierw pobiera wycenę, wypisuje kwotę i pyta Continue? [y/N]. Pytanie pomija tylko --yes; używaj go wyłącznie w skryptach, w których ktoś już zatwierdził cenę.
• MCP: każde płatne narzędzie prosi o potwierdzenie we własnym oknie klienta MCP, które klient pokazuje tobie. Zatwierdzaj je wyłącznie osobiście: agent albo klient skonfigurowany do automatycznego zatwierdzania usuwa tę granicę.
• Twoja własna automatyzacja: przed wywołaniem createTask albo retryTask pokaż wybrany model, podsumowanie danych wejściowych i wycenioną cenę, a potem uzyskaj wyraźną zgodę. Dokładną, bezpłatną wycenę pobierz z POST /api/v1/jobs/quote i wyślij zgłoszenie z jej quoteId i expectedCost, żeby zmiana ceny kończyła się błędem 40901, a nie pobraniem innej kwoty. Zobacz Wyceny i zgodność protokołów.

Materiały do odczytu maszynowego

Zacznij od najmniejszego materiału, który odpowiada na bieżące pytanie. Dzięki temu kontekst agenta pozostaje trafny i tani.

Za wiążący kontrakt uznawaj kontrakt OpenAPI i katalog modeli na żywo. Przykłady marketingowe mają charakter poglądowy i nie są źródłem schematu. Te dokumenty możesz buforować, ale odśwież je przed generowaniem kodu albo wtedy, gdy żądania zaczynają nie przechodzić walidacji.

Minimalny przepływ w SDK z zatwierdzeniem

Ten skrypt pokazuje granicę zatwierdzenia w SDK: pobiera wycenę, zatrzymuje się, jeśli nie podasz --approved, a potem tworzy zadanie po wycenionej cenie i czeka na nie. Instalację, każdą metodę i pełną ścieżkę do pierwszego wyniku znajdziesz w przewodniku po SDK dla TypeScriptu; szczegóły metod – w jego opisie API.

npm install @spicyapi/sdk
export SPICY_MODEL_ID="MODEL_ID_FROM_CATALOG"     # wartość model z katalogu na żywo
export SPICY_INPUT_JSON='{"prompt":"your prompt"}' # musi pasować do inputSchema tego modelu

import { randomUUID } from "node:crypto";
import { SpicyClient } from "@spicyapi/sdk";

const client = new SpicyClient(); // odczytuje SPICY_API_KEY
const modelId = process.env.SPICY_MODEL_ID;
if (!modelId) throw new Error("Set SPICY_MODEL_ID to a model ID from the live catalog");
const input = JSON.parse(process.env.SPICY_INPUT_JSON ?? "{}");

// Bezpłatne: wycena dokładnie tego żądania. Nic nie powstaje i nic nie zostaje zarezerwowane.
const quote = await client.quoteTask({ model: modelId, input });
console.log(`${quote.model}: up to $${quote.maxCharge}, quote valid until ${quote.expiresAt}`);

if (!process.argv.includes("--approved")) {
  console.log("Nothing was submitted. Re-run with --approved once a person has approved this amount.");
  process.exit(0);
}

// Płatne: wysłanie tego samego żądania po wycenionej cenie. W prawdziwym systemie utwórz
// i zapisz klucz idempotentności przed pierwszą próbą, a identyfikator zadania przechowuj trwale.
const accepted = await client.createTask(
  { model: modelId, input, quoteId: quote.quoteId, expectedCost: quote.estimatedCost },
  { idempotencyKey: randomUUID() },
);
console.log("accepted", accepted.taskId, "deadline", accepted.deadlineAt);

// Przerwanie czekania nigdy nie anuluje zadania; wróć do niego później z identyfikatorem zadania.
const task = await client.waitForTask(accepted.taskId, { timeoutMs: 30 * 60_000 });
console.log(JSON.stringify(task, null, 2));

npx --yes tsx run.mts              # tylko wycena, bezpłatnie
npx --yes tsx run.mts --approved   # tworzy zadanie: to kosztuje

Rozszerzenie .mts sprawia, że plik jest modułem ES, czego wymaga await na najwyższym poziomie; zwykły run.ts w projekcie utworzonym domyślnym npm init kończy się błędem Top-level await is currently not supported with the "cjs" output format. Wycena jest ważna pięć minut: jeśli zatwierdzanie trwa dłużej, uruchom ponownie pierwsze polecenie.

Proces produkcyjny

POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Content-Type: application/json
Idempotency-Key: project-42-scene-07-v1

// Cztery stany końcowe zdefiniowane dziś. Rozstrzyga strona o zadaniach: każdy stan
// inny niż queued i running jest końcowy, nawet jeśli nie ma go na tej liście.
const KNOWN_TERMINAL = ['succeeded', 'failed', 'canceled', 'expired'];

const deadline = Date.parse(accepted.deadlineAt) + 60_000;
let delay = 2_000;

while (Date.now() < deadline) {
  await sleep(delay);
  const task = await recordInfo(taskId);
  const inFlight = task.state === 'queued' || task.state === 'running';
  const assetsPending = task.state === 'succeeded' && task.output?.assets?.some((a) => a.pending);
  if (!inFlight && !assetsPending) {
    if (!KNOWN_TERMINAL.includes(task.state)) log.warn(`new terminal state: ${task.state}`);
    return task;
  }
  delay = Math.min(Math.round(delay * 1.5), 15_000);
}
throw new Error(`task ${taskId} exceeded the polling deadline`);

Minimalny trwały rekord

Przechowuj tyle stanu, żeby po restarcie bezpiecznie wznowić pracę:

{
  "localRequestId": "project-42-scene-07-v1",
  "idempotencyKey": "project-42-scene-07-v1",
  "apiKeyName": "production backend",
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "approvedCost": "0.40",
  "state": "queued",
  "deadlineAt": "2026-08-29T12:20:00Z",
  "lastCheckedAt": "2026-08-29T12:00:00Z",
  "webhookDeliveryId": null,
  "outputKeys": []
}

MODEL_ID_FROM_CATALOG oznacza dokładny identyfikator wybrany z uwierzytelnionego katalogu na żywo, a nie dosłowną wartość do wysłania. Zapisuj, który klucz API utworzył zadanie: tylko ten klucz może je odczytać albo ponowić. Nigdy nie używaj podpisanego adresu do pobrania jako trwałego klucza. Nigdy nie wnioskuj o powodzeniu z HTTP 200; czytaj data.state.

Makiety, zanim wydasz pieniądze

Zbuduj lokalną makietę kontraktu wokół struktur odpowiedzi opisanych na stronach Zadania asynchroniczne, Webhooki i Błędy. Twój zestaw danych testowych powinien obejmować:

• queued → running → succeeded;
• niepowodzenie końcowe z code: 200 i data.state: "failed";
• zdublowane odpowiedzi createTask zwracające to samo taskId;
• wycenę, która już nie pasuje (40901), i za niskie saldo (40201);
• prawidłowy webhook, nieprawidłowy podpis i powtórzone dostarczenie;
• 429, 503, przekroczenie czasu na poziomie połączenia i zadanie, które przekracza termin odpytywania;
• wygasły adres do pobrania, który trzeba wystawić ponownie.

Makiety sprawdzają orkestrację, a nie jakość modelu. Przed wydaniem uruchom jedno małe, prawdziwe zadanie na dokładnie tym modelu i z dokładnie tym kształtem danych wejściowych, których używasz na produkcji.

Lista kontrolna odbioru

• Sekrety istnieją wyłącznie w magazynie sekretów po stronie serwera i są maskowane w logach.
• Integracja pobiera aktualny schemat modelu, zamiast zgadywać pola.
• Człowiek zatwierdza wycenioną cenę przed każdym płatnym wywołaniem, a zgłoszenia zawierają quoteId i expectedCost.
• Jedno logiczne żądanie ma jeden trwale zapisany Idempotency-Key, wysyłany zawsze z tym samym kluczem API.
• taskId jest zapisywane, zanim praca pójdzie dalej, i przetrwa restart procesu.
• Odpytywanie wydłuża przerwy, ma maksymalny odstęp i termin według zegara.
• Webhooki weryfikują znacznik czasu, skrót surowej treści i HMAC, a potem odfiltrowują zdublowane identyfikatory dostarczeń.
• Niepowodzenie końcowe jest odczytywane z data.state, a nie ze statusu HTTP ani z code w strukturze odpowiedzi.
• Potrzebne wyniki są kopiowane do własnego magazynu, zanim wygaśnie adres URL albo okres przechowywania. taskId i klucze obiektów są zachowywane do uzgadniania, a nie jako sposób na pobieranie plików po końcu okresu przechowywania.
• Logi zachowują request_id, taskId, model i liczbę prób, bez promptów i sekretów.
• Testy na makietach obejmują zdublowane tworzenie, powtórzenie, przekroczenie czasu, limit żądań i wygasłe media.