Ir al contenido principal

SDK oficiales

SDK oficiales para cinco lenguajes

Instala un paquete y llama a modelos de imagen, video y audio desde tu propio servidor. El SDK se encarga de la autenticación y de esperar los resultados: tú solo escribes la solicitud y lees la respuesta.

Lo que el SDK hace por ti

Tú escribes una sola llamada. El SDK autentica la solicitud, sube tus archivos, espera el resultado y te lo devuelve como datos tipados.

  1. Tu códigoUna sola llamada
  2. SDK oficialAutentica solicitudes, sube archivos y espera resultados
  3. Modelos de imagen, video y audioLos mismos modelos y precios que la web
Sin SDK envías tú mismo las mismas solicitudes por HTTPS. El SDK solo te ahorra el código repetitivo.

Ideal para

  • Servicios de backendGenera contenido desde tu propia API o cola de trabajos.
  • Scripts y procesos por lotesCrea muchas tareas desde una hoja de cálculo o un trabajo programado.
  • Apps con servidorGuarda la clave en el servidor y envía los archivos terminados a tus usuarios.

Empieza en tres pasos

  1. Paso 1

    Crea una clave de API

    Genera una en la consola y guárdala como SPICY_API_KEY en tu servidor.

  2. Paso 2

    Instala el paquete

    Elige tu lenguaje más abajo y ejecuta la línea de instalación.

  3. Paso 3

    Crea una tarea y lee el resultado

    Envía un prompt, espera la tarea y guarda el archivo que devuelve.

Elige tu lenguaje

Cada SDK se publica en el registro principal de su lenguaje y usa la misma API. Cambia de pestaña para ver la línea de instalación y una solicitud completa.

TypeScript

@spicyapi/sdk

Requiere Node.js 22.13+

Tu servidor crea tareas y guarda resultados. Instalar, exportar la clave, ejecutar.

Instalación · bash
npm install @spicyapi/sdk
export SPICY_API_KEY="injected from your secret manager"
Crear una tarea y leer el 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);

Qué pasa después de enviar

La generación de imagen y video sigue en marcha cuando la llamada de creación ya ha respondido. Guarda el ID de la tarea y deja que un webhook, o una consulta de estado con límite de tiempo, te avise cuando termine.

  1. createTaskEnvía con una clave de idempotencia: la misma generación solo se acepta una vez.
  2. taskIdLa respuesta vuelve al instante mientras la tarea sigue en marcha.
  3. Webhook / recordInfoRecibe primero un webhook firmado; usa consultas de estado acotadas solo para recuperar el resultado.
  4. output.assetsURLs listas para usar. Copia lo que quieras conservar.

Llamadas desde un navegador o una app móvil

Una clave incluida en una app cliente queda expuesta a sus usuarios. Mantenla en tu servidor: @spicyapi/proxy añade la credencial a las solicitudes de tu frontend, de modo que la app nunca la ve.

  • Clave dentro de la appCualquiera puede leerla y gastar tu saldo.
    1. App con la clave dentro
    2. SpicyAPI
  • Clave en tu servidorLa app habla con tu servidor y el proxy añade la clave.
    1. Navegador o móvil
    2. Tu 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 salir a producción

  • 01Confirmar la disponibilidad actual.
  • 02Validar los campos exactos de la página.
  • 03Mantener la clave API en el servidor.
  • 04Mostrar la estimación antes de enviar.
  • 05Guardar taskId fuera de la sesión del navegador.
  • 06Verificar la firma webhook o el límite de comprobaciones.
  • 07Tratar una tarea aceptada como no cancelable.

Soluciona errores comunes

Casi todos los problemas del principio son uno de estos tres. Cada tarjeta muestra lo que ves y lo único que debes cambiar.

  • 401

    Clave de API no válida

    A la API no llegó ninguna clave, o llegó una incorrecta. Define SPICY_API_KEY en el mismo entorno donde se ejecuta tu código.

  • espera

    La tarea sigue en curso

    Un video puede tardar unos minutos. Espera con un límite de tiempo o usa un webhook. Si reenvías sin la misma Idempotency-Key, se crea una segunda tarea de pago.

  • enlace

    El enlace del resultado caducó

    Los enlaces de descarga duran poco. Pide un enlace nuevo para la tarea en lugar de guardar el anterior.

Preguntas frecuentes