Каталог моделей и схемы

createTask.model принимает точное значение model из авторизованного ответа GET /api/v1/models. Формат input определяет текущая inputSchema той же записи. Именно этот ответ во время выполнения — единственный достоверный источник ID, доступных для вызова.

В примерах этой страницы MODEL_ID_FROM_CATALOG — заполнитель, а не настоящая модель: замените его значением model из своего актуального каталога. Чтение каталога бесплатно.

Выберите модель вместе с проверенными входными данными

Схемы запросов различаются между моделями, поэтому для надёжного запуска выбирайте одновременно доступную модель и один из её примеров, проверенных сервером:

const response = await fetch(
  'https://api.spicyapi.ai/api/v1/models?includeSchema=1&includeExamples=1',
  { headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` } },
);
const envelope = await response.json();
if (!response.ok || envelope.code !== 200) throw new Error(envelope.msg);

const selected = envelope.data.items.find(
  (item) => item.enabled && item.available && item.examples?.length,
);
if (!selected) throw new Error('No callable model with a validated example');

const createTaskBody = {
  model: selected.model,
  input: selected.examples[0].input,
};

Каждый пример — полный input, который сервер уже проверил по текущей схеме, поэтому его можно отправлять без изменений.

Читайте каталог программно

GET /api/v1/models
GET /api/v1/models/{model}

curl "https://api.spicyapi.ai/api/v1/models?modality=video" \
  -H "Authorization: Bearer $SPICY_API_KEY"

Список не разделён на страницы: один ответ содержит все видимые вашему ключу модели, соответствующие фильтрам. Все параметры необязательны.

Эндпоинт одной модели, GET /api/v1/models/{model}, всегда включает inputSchema и examples; includeSchema и includeExamples имеют значение только для списка. Косые черты в ID можно оставлять как есть; кодируйте их через процентное представление только если HTTP-клиент считает параметр пути одним сегментом. Несуществующая или сейчас не предлагаемая модель возвращает 404.

Сокращённый ответ со списком:

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 1,
    "items": [
      {
        "model": "MODEL_ID_FROM_CATALOG",
        "family": "…",
        "displayName": "…",
        "provider": "…",
        "modality": "video",
        "tasks": ["image-to-video"],
        "async": true,
        "enabled": true,
        "available": true,
        "availability": "available",
        "taskTimeoutSeconds": 1200,
        "maxOutputDurationSeconds": 10,
        "quantityField": "duration_seconds",
        "pricing": [
          { "variant": "generate_audio=false;resolution=720p", "unit": "per_second", "price": "0.05", "currency": "USD" },
          { "variant": "generate_audio=true;resolution=720p", "unit": "per_second", "price": "0.08", "currency": "USD" }
        ],
        "startingPrice": { "variant": "generate_audio=false;resolution=720p", "unit": "per_second", "price": "0.05", "currency": "USD" },
        "badges": ["audio_output"],
        "relatedModels": [],
        "version": "v1",
        "updatedAt": "2026-09-16T16:47:57Z"
      }
    ]
  },
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

Цены выше приведены для иллюстрации. inputSchema и examples появляются в элементах списка только по запросу.

Поля, которые следует использовать клиентам

mature и policyTier — информационные метки. Они никак не участвуют в решении о принятии запроса.

Как читать цены

Каждая запись в pricing — одна ценовая категория:

startingPrice — самая дешёвая категория, а не цена ваших настроек. Поля выбора категории перечислены в inputSchema["x-pricing"].variantFields, если оно есть, а иначе — это поля с пометкой x-ui.affects_price: true (кроме quantityField). Пропущенное поле учитывается со своим значением default из схемы.

• Медиамодели: стоимость равна price × quantity, где количество — значение quantityField во входных данных (или одна единица, если quantityField пусто). Некоторые эндпоинты затем добавляют отдельную плату за каждый дополнительный входной файл, чаще всего за каждое референсное изображение. Это полноценная часть счёта, а не мелочь округления: на эндпоинте редактирования, принимающем массив референсов, заполнение массива может увеличить сумму в несколько раз. При этом unit, quantity, variant и цена категории price остаются такими же, как для одного изображения, — поэтому формула выше занижает сумму без видимого признака. Машиночитаемый признак — поле с пометкой x-ui.affects_price: true, которое не является quantityField и не входит в x-pricing.variantFields: оно меняет сумму, но не выбирает категорию. Для такого эндпоинта считайте pricing нижней границей, а сумму берите из расчёта цены.
• Текстовые модели (per_1k_tokens): одно число не описывает всю оплату. price — только тариф выходных токенов за 1000 токенов. Для входных и кешированных входных токенов действуют отдельные, обычно меньшие тарифы; они оплачиваются по измеренному использованию каждого вызова. Не умножайте price на общее число токенов. Цены за миллион входных, кешированных входных и выходных токенов показаны на странице каждой модели и в price.perMillionTokens публичного каталога.

Чтобы узнать сумму конкретного запроса нативного API до оплаты, используйте POST /api/v1/jobs/quote. Итоговые списания находятся в записи задачи (cost с settled: true) и в разделе Оплата.

Кеширование каталога

• Ответ каталога можно кешировать до 60 секунд (Cache-Control: private, max-age=60). Храните его только в приватном кеше отдельного аккаунта: цены зависят от аккаунта, поэтому общий или публичный CDN-кеш использовать нельзя.
• После этого не перечитывайте каталог перед каждой задачей. Чтение каталога расходует лимит чтения аккаунта независимо от отправки задач. Запрос каталога перед каждым вызовом всё равно расходует лишнюю квоту чтения; см. Ограничения частоты запросов.
• Обновляйте его по таймеру (например, раз в несколько минут), после ошибки валидации 400 и при отклонении отправки запроса к этой модели.
• Сохраняйте version и updatedAt использованной записи, чтобы понять, изменилось ли что-либо при последующем чтении.
• Не распространяйте жёстко зафиксированный снимок схемы и никогда не подменяйте каталог статической страницей, если в актуальном каталоге нет доступной для вызова записи.

Общие правила Schema и Playground

inputSchema использует JSON Schema 2020-12. Стандартные ключевые слова управляют серверной валидацией; объект x-ui на уровне свойства описывает только порядок в Playground, отображение и подсказки об обновлении цены. Клиенты должны игнорировать неизвестные расширения отображения; они никогда не заменяют required, перечисления, границы и условные ветви. См. полный Контракт Spicy Schema.

Создайте собственную таблицу параметров модели

На этом сайте нет статической таблицы параметров для каждой модели. Дело не в нежелании её делать: модели и поля меняются каждую неделю, любая статическая копия устаревает, а чтение устаревшего параметра приводит к 400 или неверной цене. У параметров ровно один источник — inputSchema из каталога. Playground отображает тот же документ, а SDK проверяет данные по нему.

Как части схемы превращаются в таблицу

Условные ветви появляются только в корне inputSchema и имеют две формы: anyOf, где каждая ветвь перечисляет только поля required («передайте хотя бы одно из этих полей»), и allOf, где каждая ветвь — if → then («если передаёте A, нужно передать B»). Не выводите условия из семейства модели и не ожидайте oneOf, not или dependentSchemas. Новые эндпоинты следуют единым полям Spicy Schema; старые — своей актуальной схеме.

Получение схемы

const modelId = 'MODEL_ID_FROM_CATALOG'; // the exact `model` value from GET /api/v1/models
const res = await fetch(`https://api.spicyapi.ai/api/v1/models/${modelId}`, {
  headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` },
});
const { data } = await res.json();
const schema = data.inputSchema;

const rows = Object.entries(schema.properties)
  .sort(([, a], [, b]) => (b['x-ui']?.order ?? 0) - (a['x-ui']?.order ?? 0))
  .map(([name, prop]) => ({
    name,
    required: (schema.required ?? []).includes(name),
    type: prop.type,
    description: prop.description,
    values: prop.enum
      ? prop.enum.map((v) => prop['x-ui']?.enum_labels?.[v] ?? v)
      : prop.minimum !== undefined || prop.maximum !== undefined
        ? [`${prop.minimum ?? ''}–${prop.maximum ?? ''}${prop['x-ui']?.unit ?? ''}`]
        : [],
    default: prop.default,
    affectsPrice: prop['x-ui']?.affects_price === true,
    advanced: prop['x-ui']?.advanced === true,
  }));

Этот пример намеренно ограничен скалярными значениями: для массива он оставляет values пустым, поскольку допустимое содержимое массива задаётся через items, minItems и maxItems, а не через enum или диапазон. Расширьте пример до использования в рабочем продукте: если строка показывает параметр лишь как array, без формата записи и ограничения длины, читатель не сможет по ней подготовить данные.

Запись одной модели также возвращает examples: каждый пример — полный набор входных данных, уже проверенный сервером по текущей схеме. Он подходит и как минимальный рабочий пример документации, и как тело запроса, которое можно отправить без изменений. Это надёжнее ручного составления: ручной пример устаревает при изменении схемы, а examples — нет.

Тот же код охватывает любую модель при замене modelId и не устаревает при добавлении новых моделей. Чтобы построить таблицу для всего каталога, переберите items из GET /api/v1/models?includeSchema=1 и кешируйте результат, как описано в разделе Кеширование каталога.

Более подробные пояснения, чем description

description — одно предложение, рассчитанное на подпись поля формы. Если параметру нужны дополнительные пояснения, публичный каталог содержит вторую заметку для каждого параметра:

curl "https://api.spicyapi.ai/console/v1/catalog/models/MODEL_ID_FROM_CATALOG?locale=en"

Запись одной модели возвращает paramNotes — объект с именами параметров в качестве ключей; через locale доступен текст на любом из десяти языков документации. Здесь объясняется то, что не помещается в подпись: относительно чего на самом деле измеряется значение, какая настройка заметно замедляет вызов и какие входные данные проходят схему, но всё равно дают неудовлетворительный результат. Для параметра, указывающего на размещённый вами файл, это обычно единственное место, где объясняется, загружаем ли мы его, когда именно и что будет, если файл окажется непригодным.

Две границы: paramNotes находится в публичном каталоге, не требующем ключа, а не в авторизованном GET /api/v1/models. Поэтому читайте его отдельно и кешируйте рядом со схемой. Кроме того, это поясняющий текст, а не правило: только inputSchema определяет, принимается ли запрос.