Pular para o conteúdo principal

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.

  1. Seu códigoUma chamada de função
  2. SDK oficialAssina requisições, envia arquivos, espera resultados
  3. Modelos de imagem, vídeo e áudioOs mesmos modelos e preços do site
Sem SDK, você envia as mesmas requisições por HTTPS. O SDK só tira o trabalho repetitivo.

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

  1. Passo 1

    Crie uma chave de API

    Gere uma no console e guarde-a como SPICY_API_KEY no seu servidor.

  2. Passo 2

    Instale o pacote

    Escolha sua linguagem abaixo e rode a linha de instalação.

  3. 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/sdk

Requer Node.js 22.13+

Seu servidor cria tarefas e guarda resultados. Instalar, exportar a chave, executar.

Instalação · bash
npm install @spicyapi/sdk
export SPICY_API_KEY="injected from your secret manager"
Criar uma tarefa e ler o resultado · ts
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);

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.

  1. createTaskEnvie com uma chave de idempotência: a mesma geração só é aceita uma vez.
  2. taskIdA resposta volta na hora enquanto a tarefa continua rodando.
  3. Webhook / recordInfoPrefira um webhook assinado; use consultas com limite apenas para recuperação.
  4. 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.
    1. App com a chave dentro
    2. SpicyAPI
  • Chave no seu servidorO app fala com o seu servidor, e o proxy adiciona a chave.
    1. Navegador ou celular
    2. Seu servidor + proxy
    3. SpicyAPI
@spicyapi/proxy
npm install @spicyapi/proxy
next.js
// 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.

Perguntas frequentes