Перейти к основному контенту

Официальные SDK

Официальные SDK для пяти языков

Установите один пакет и вызывайте модели изображений, видео и аудио со своего сервера. Аутентификацию и ожидание результата берёт на себя SDK — вам остаётся написать запрос и прочитать ответ.

Что SDK делает за вас

Вы пишете один вызов функции. SDK подписывает запрос, загружает файлы, дожидается результата и возвращает его в виде типизированных данных.

  1. Ваш кодОдин вызов функции
  2. Официальный SDKПодписывает запросы, грузит файлы, ждёт результат
  3. Модели для изображений, видео и аудиоТе же модели и цены, что на сайте
Без SDK вы отправляете такие же запросы сами, по HTTPS. SDK просто убирает рутину.

Подходит для

  • Бэкенд-сервисыГенерируйте медиа прямо в своём API или очереди задач.
  • Скрипты и пакетная обработкаСоздавайте много задач из таблицы или по расписанию.
  • Приложения с серверомХраните ключ на сервере, а готовые файлы отдавайте пользователям.

Начните за три шага

  1. Шаг 1

    Создайте API-ключ

    Создайте его в консоли и сохраните на сервере как SPICY_API_KEY.

  2. Шаг 2

    Установите пакет

    Выберите свой язык ниже и выполните команду установки.

  3. Шаг 3

    Создайте задачу и получите результат

    Отправьте промпт, дождитесь завершения задачи и сохраните возвращённый файл.

Выберите язык

Каждый SDK опубликован в основном реестре своего языка и работает с тем же API. Переключайте вкладки, чтобы увидеть команду установки и полный пример запроса.

TypeScript

@spicyapi/sdk

Требуется Node.js 22.13+

Ваш сервер создаёт задачи и хранит результаты. Установить, экспортировать ключ, запустить.

Установка · bash
npm install @spicyapi/sdk
export SPICY_API_KEY="injected from your secret manager"
Создать задачу и получить результат · 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);

Что происходит после отправки

Генерация изображений и видео продолжается и после того, как вызов создания вернул ответ. Сохраните ID задачи, а о завершении узнайте через вебхук или ограниченную по времени проверку статуса.

  1. createTaskОтправляйте с ключом идемпотентности: одна генерация принимается ровно один раз.
  2. taskIdОтвет приходит сразу, а задача продолжает выполняться.
  3. Webhook / recordInfoПредпочитайте подписанный вебхук; ограниченный опрос используйте только для восстановления.
  4. output.assetsГотовые ссылки. То, что нужно сохранить, копируйте к себе.

Вызовы из браузера или мобильного приложения

Ключ, встроенный в клиентское приложение, доступен его пользователям. Храните его на сервере: @spicyapi/proxy добавляет учётные данные к запросам вашего фронтенда, поэтому приложение их не видит.

  • Ключ внутри приложенияЛюбой может его прочитать и потратить ваш баланс.
    1. Приложение с ключом внутри
    2. SpicyAPI
  • Ключ на вашем сервереПриложение обращается к вашему серверу, а прокси подставляет ключ.
    1. Браузер или телефон
    2. Ваш сервер + прокси
    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";

Перед запуском

  • 01Проверить текущую доступность модели.
  • 02Проверить точные поля со страницы модели.
  • 03Хранить API-ключ только на сервере.
  • 04Показать оценку до отправки.
  • 05Сохранить taskId вне браузерной сессии.
  • 06Проверить подпись webhook или ограничение запросов статуса.
  • 07Считать принятую задачу неотменяемой.

Частые ошибки и как их исправить

Почти все проблемы на старте — одна из этих трёх. На каждой карточке: что вы видите и что нужно изменить.

  • 401

    Недействительный API-ключ

    В API пришёл неверный ключ или никакой. Задайте SPICY_API_KEY в том же окружении, где запускается ваш код.

  • wait

    Задача ещё выполняется

    Видео может генерироваться несколько минут. Ждите с ограничением по времени или используйте вебхук. Повторная отправка без того же Idempotency-Key создаст вторую платную задачу.

  • ссылка

    Ссылка на результат устарела

    Ссылки для скачивания живут недолго. Запросите у задачи свежую ссылку, а не храните старую.

Частые вопросы