SDKs oficiais
SDKs oficiais para cinco linguagens
Instale um pacote e chame modelos de imagem, vídeo e áudio a partir do seu próprio servidor. O SDK cuida da autenticação e da espera pelos resultados; você só escreve a requisição e lê a resposta.
O que o SDK faz por você
Você escreve uma única chamada de função. O SDK assina a requisição, envia seus arquivos, espera o resultado e devolve tudo como dados tipados.
- Seu códigoUma chamada de função
- SDK oficialAssina requisições, envia arquivos, espera resultados
- Modelos de imagem, vídeo e áudioOs mesmos modelos e preços do site
Ideal para
- Serviços de backendGere mídia dentro da sua própria API ou fila de jobs.
- Scripts e lotesCrie muitas tarefas a partir de uma planilha ou de um job agendado.
- Apps com servidorMantenha a chave no servidor e entregue os arquivos prontos aos usuários.
Comece em três passos
- Passo 1
Crie uma chave de API
Gere uma no console e guarde-a como SPICY_API_KEY no seu servidor.
- Passo 2
Instale o pacote
Escolha sua linguagem abaixo e rode a linha de instalação.
- Passo 3
Crie uma tarefa e leia o resultado
Envie um prompt, espere a tarefa e salve o arquivo que ela devolve.
Escolha sua linguagem
Cada SDK é publicado no registro principal da sua linguagem e fala com a mesma API. Troque de aba para ver a linha de instalação e uma requisição completa.
TypeScript
@spicyapi/sdkRequer Node.js 22.13+
Seu servidor cria tarefas e guarda resultados. Instalar, exportar a chave, executar.
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
spicyapiRequer Python 3.11+
A mesma sequência em Python: estimar o preço, criar a tarefa e aguardar um estado final.
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-goRequer Go 1.23+
Só biblioteca padrão, então nada novo entra no seu grafo de módulos. Já dá para usar com 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/spicyapiRequer PHP 8.1+, ext-json, ext-hash
Arrays associativos e argumentos nomeados, sem nenhuma dependência.
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.0Requer Java 17+, Jackson
Records e Jackson; run() faz criação e espera de uma vez.
<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);
}O que acontece depois do envio
A geração de imagem e vídeo continua rodando depois que a chamada de criação responde. Guarde o ID da tarefa e deixe um webhook, ou uma consulta de status com tempo limite, avisar quando terminar.
- createTaskEnvie com uma chave de idempotência: a mesma geração só é aceita uma vez.
- taskIdA resposta volta na hora enquanto a tarefa continua rodando.
- Webhook / recordInfoPrefira um webhook assinado; use consultas com limite apenas para recuperação.
- output.assetsURLs prontas para uso. Guarde uma cópia do que precisa manter.
Chamadas a partir de um navegador ou app mobile
Uma chave dentro de um app cliente é uma chave pública. Mantenha-a no seu servidor: o @spicyapi/proxy adiciona a credencial às requisições do seu front-end, e o app nunca a vê.
- Chave dentro do appQualquer pessoa pode lê-la e gastar o seu saldo.
- App com a chave dentro
- SpicyAPI
- Chave no seu servidorO app fala com o seu servidor, e o proxy adiciona a chave.
- Navegador ou celular
- Seu servidor + proxy
- SpicyAPI
npm install @spicyapi/proxy// app/api/spicy/proxy/route.ts
export { GET, POST } from "@spicyapi/proxy/nextjs";
export const runtime = "nodejs";Antes de ir para produção
- 01Confirmar a disponibilidade atual.
- 02Validar os campos exatos da página.
- 03Manter a chave no servidor.
- 04Mostrar a estimativa antes do envio.
- 05Guardar taskId fora da sessão do navegador.
- 06Verificar assinatura webhook ou limite de consultas.
- 07Tratar tarefa aceita como não cancelável.
Corrija os erros mais comuns
A maioria dos problemas de primeira viagem é um destes três. Cada card mostra o que você vê e a única coisa a mudar.
- 401
Chave de API inválida
Nenhuma chave, ou uma chave errada, chegou à API. Defina SPICY_API_KEY no mesmo ambiente em que seu código roda.
- espera
Tarefa ainda em andamento
Vídeos podem levar alguns minutos. Espere com um tempo limite ou use um webhook. Reenviar sem a mesma Idempotency-Key cria uma segunda tarefa paga.
- link
Link do resultado expirou
Os links de download duram pouco. Peça um link novo para a tarefa em vez de guardar o antigo.
