Oficjalne SDK
Oficjalne SDK dla pięciu języków
Zainstaluj jeden pakiet i wywołuj modele obrazu, wideo i dźwięku z własnego serwera. SDK zajmuje się uwierzytelnianiem i oczekiwaniem na wyniki, a Ty piszesz tylko żądanie i odczytujesz odpowiedź.
Co SDK robi za Ciebie
Piszesz jedno wywołanie funkcji. SDK podpisuje żądanie, wysyła Twoje pliki, czeka na wynik i oddaje go jako typowane dane.
- Twój kodJedno wywołanie funkcji
- Oficjalne SDKPodpisuje żądania, wysyła pliki, czeka na wyniki
- Modele obrazu, wideo i dźwiękuTe same modele i ceny co na stronie
Do czego się nadaje
- Usługi backendoweGeneruj media wewnątrz własnego API lub kolejki zadań.
- Skrypty i zadania wsadoweTwórz wiele zadań z arkusza lub z zaplanowanego zadania.
- Aplikacje z serweremTrzymaj klucz na serwerze i wysyłaj gotowe pliki użytkownikom.
Start w trzech krokach
- Krok 1
Utwórz klucz API
Wygeneruj go w konsoli i zapisz na serwerze jako SPICY_API_KEY.
- Krok 2
Zainstaluj pakiet
Wybierz poniżej swój język i uruchom komendę instalacji.
- Krok 3
Utwórz zadanie, odczytaj wynik
Wyślij prompt, poczekaj na zadanie, a potem zapisz zwrócony plik.
Wybierz swój język
Każde SDK jest publikowane w głównym rejestrze danego języka i korzysta z tego samego API. Przełączaj karty, aby zobaczyć komendę instalacji i pełne żądanie.
TypeScript
@spicyapi/sdkWymaga: Node.js 22.13+
Twój serwer tworzy zadania i przechowuje wyniki. Instalacja, eksport klucza, uruchomienie.
npm install @spicyapi/sdk
export SPICY_API_KEY="injected from your secret manager"import { randomUUID } from "node:crypto";
import { SpicyClient } from "@spicyapi/sdk";
const client = new SpicyClient();
const model = await client.getModel("MODEL_ID_FROM_CATALOG");
const task = await client.run(
{ model: model.model, input: { prompt: "A cinematic night portrait" } },
{ idempotencyKey: randomUUID() },
);
console.log(task.state, task.output?.assets?.[0]?.url);Python
spicyapiWymaga: Python 3.11+
Ta sama ścieżka po pythonowemu: wycena, utworzenie zadania, czekanie na stan końcowy.
pip install spicyapi
export SPICY_API_KEY="injected from your secret manager"import uuid
from spicyapi import SpicyClient, output_assets
client = SpicyClient() # reads SPICY_API_KEY from the environment
model = client.get_model("MODEL_ID_FROM_CATALOG")
quote = client.quote_task(
model=model["model"],
input_data={"prompt": "A cinematic night portrait"},
)
print(quote["estimatedCost"], quote["maxCharge"]) # decide before you spend
task = client.create_task(
model=model["model"],
input_data={"prompt": "A cinematic night portrait"},
idempotency_key=str(uuid.uuid4()),
quote_id=quote["quoteId"],
expected_cost=quote["estimatedCost"],
)
final = client.wait_for_terminal(task["taskId"])
for asset in output_assets(final):
print(asset["url"])Go
github.com/spicyapi-ai/spicy-goWymaga: Go 1.23+
Wyłącznie biblioteka standardowa, więc twój graf modułów ani drgnie. Dostępne od zaraz przez go get.
go get github.com/spicyapi-ai/spicy-go
export SPICY_API_KEY="injected from your secret manager"client, err := spicy.New(spicy.Options{}) // reads SPICY_API_KEY from the environment
if err != nil {
return err
}
request := spicy.CreateTaskInput{
Model: "MODEL_ID_FROM_CATALOG",
Input: map[string]any{"prompt": "A cinematic night portrait"},
}
quote, err := client.Quote(ctx, request)
if err != nil {
return err
}
request.QuoteID = quote.QuoteID
request.ExpectedCost = quote.EstimatedCost
// Store this next to your own record of the job before sending it: its whole
// purpose is to still be there after the crash that lost the response.
key, err := spicy.NewIdempotencyKey()
if err != nil {
return err
}
task, err := client.CreateTask(ctx, request, key, spicy.CreateTaskOptions{})
if err != nil {
return err
}
final, err := client.WaitForTerminal(ctx, task.TaskID, spicy.WaitOptions{})
if err != nil {
return err
}
for _, asset := range final.ReadyAssets() {
log.Println(asset.URL)
}PHP
spicyapi/spicyapiWymaga: PHP 8.1+, ext-json, ext-hash
Tablice asocjacyjne i argumenty nazwane, zero zależności.
composer require spicyapi/spicyapiuse SpicyApi\SpicyClient;
$client = new SpicyClient(); // reads SPICY_API_KEY from the environment
$quote = $client->quote('MODEL_ID_FROM_CATALOG', ['prompt' => 'A cinematic night portrait']);
printf("at most %s\n", $quote['maxCharge']); // decide before you spend
$task = $client->createTask(
model: $quote['model'],
input: ['prompt' => 'A cinematic night portrait'],
idempotencyKey: SpicyClient::idempotencyKey(),
quoteId: $quote['quoteId'],
expectedCost: $quote['estimatedCost'],
);
$final = $client->waitForTerminal($task['taskId']);
foreach (SpicyClient::readyAssets($final) as $asset) {
echo $asset['url'], "\n";
}Java
ai.spicyapi:spicyapi-java:0.1.0Wymaga: Java 17+, Jackson
Rekordy i Jackson, a run() załatwia utworzenie i oczekiwanie za jednym razem.
<dependency>
<groupId>ai.spicyapi</groupId>
<artifactId>spicyapi-java</artifactId>
<version>0.1.0</version>
</dependency>SpicyClient client = SpicyClient.builder().apiKeyFromEnvironment().build();
CreateTaskRequest request = CreateTaskRequest.of(
"MODEL_ID_FROM_CATALOG",
Map.of("prompt", "A cinematic night portrait"));
TaskQuote quote = client.quote(request); // free; reserves nothing
System.out.println("this will cost at most " + quote.maxCharge());
TaskRecord task = client.run( // createTask + waitForTerminal
request.withQuote(quote), UUID.randomUUID().toString());
// Transcription and similar endpoints answer in text and return no files at all.
task.outputText().ifPresent(System.out::println);
for (TaskAsset asset : task.assets()) {
asset.url().ifPresent(System.out::println);
}Co dzieje się po wysłaniu
Generowanie obrazu i wideo trwa dalej, gdy wywołanie tworzące już zwróci odpowiedź. Zapisz ID zadania, a o zakończeniu poinformuje Cię webhook albo sprawdzenie statusu z limitem czasu.
- createTaskWyślij żądanie z kluczem idempotentności, aby dane generowanie zostało przyjęte tylko raz.
- taskIdOdpowiedź wraca natychmiast, a zadanie pracuje dalej.
- Webhook / recordInfoW pierwszej kolejności podpisany webhook; ograniczone odpytywanie służy do odzyskiwania wyników.
- output.assetsGotowe do użycia adresy. Zachowaj własną kopię wszystkiego, co ma znaczenie.
Wywołania z przeglądarki lub aplikacji mobilnej
Klucz zapisany w aplikacji klienckiej jest dostępny dla użytkowników. Trzymaj go na serwerze: @spicyapi/proxy dodaje go do żądań z frontendu, dzięki czemu aplikacja go nie widzi.
- Klucz w aplikacjiKażdy może go odczytać i wydać Twoje saldo.
- Aplikacja z kluczem w środku
- SpicyAPI
- Klucz na Twoim serwerzeAplikacja łączy się z Twoim serwerem, a proxy dodaje klucz.
- Przeglądarka lub telefon
- Twój serwer + proxy
- SpicyAPI
npm install @spicyapi/proxy// app/api/spicy/proxy/route.ts
export { GET, POST } from "@spicyapi/proxy/nextjs";
export const runtime = "nodejs";Zanim ruszysz na produkcję
- 01Sprawdź, czy model jest w tej chwili dostępny.
- 02Zweryfikuj dokładne pola pokazane na jego stronie modelu.
- 03Trzymaj klucz API wyłącznie na serwerze.
- 04Pokaż szacowany koszt przed wysłaniem.
- 05Zapisuj taskId poza sesją przeglądarki.
- 06Weryfikuj podpisy webhooków albo ograniczaj odpytywanie statusu.
- 07Traktuj przyjęte zadanie jako ostateczne i nieodwołalne.
Typowe błędy i poprawki
Pierwsze problemy zwykle sprowadzają się do tych trzech sytuacji. Każda karta opisuje objaw i jedną zmianę, która go rozwiązuje.
- 401
Nieprawidłowy klucz API
API nie otrzymało klucza lub otrzymało nieprawidłowy klucz. Ustaw SPICY_API_KEY w środowisku, w którym działa Twój kod.
- czekaj
Zadanie nadal trwa
Generowanie wideo może trwać kilka minut. Poczekaj z określonym limitem czasu lub użyj webhooka. Ponowne wysłanie bez tego samego Idempotency-Key tworzy drugie płatne zadanie.
- link
Link do wyniku wygasł
Linki do pobrania są krótkotrwałe. Poproś o nowy link do zadania zamiast zapisywać stary.
