Глоссарий

Продукт — это API, поэтому в документации не обойтись без технических слов. На этой странице каждое из них объяснено простым языком. Статьи идут в алфавитном порядке английских названий: именно так термины выглядят в коде, в ответах API и в интерфейсах инструментов. Каждая статья состоит из трёх частей: что слово означает в целом, что оно означает в SpicyAPI и на какой странице собраны все подробности.

Другие страницы ссылаются прямо на нужную статью, так что если где-то вас остановило незнакомое слово, скорее всего, оно есть здесь. Общую картину даёт страница Как устроен SpicyAPI.

Agent Skill

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

В SpicyAPI: официальный Skill, опубликованный как @spicyapi/skill, учит ассистентов вроде Claude Code, Codex или Cursor правильно работать со SpicyAPI: читать актуальный каталог, а не угадывать, показывать вам цену перед платной работой, повторно использовать ключи идемпотентности и никогда не вставлять ваш API-ключ в код. Установите его командой npx skills add spicyapi-ai/spicy-skill. Он хорошо работает в паре с MCP-сервером.

Подробнее: Agent Skill

API

Сокращение от application programming interface — программный интерфейс приложения: фиксированный набор запросов, которые одна программа может отправлять другой, и ответов, которые она получает. Сайт сделан для того, чтобы по нему кликали люди; API сделан для того, чтобы его вызывали программы.

В SpicyAPI: через API к моделям обращаются все инструменты. Песочница, CLI, MCP-сервер и SDK отправляют на api.spicyapi.ai те же самые запросы, что может отправлять и ваш собственный код.

Подробнее: OpenAPI и список эндпоинтов

API-ключ (API key)

Секретная строка, которая доказывает, что запрос пришёл от вас. Относитесь к нему как к паролю, которым пользуются программы.

В SpicyAPI: ключи начинаются с sk-spicy- и создаются на странице Ключи API в консоли. Ключ показывается только один раз; если вы его потеряли, создайте новый. В каждом запросе ключ передаётся в заголовке Authorization: Bearer. Храните ключи на своём компьютере или сервере и никогда — на веб-странице, в мобильном приложении, в публичном репозитории, на скриншоте или в переписке. Для каждого ключа можно задать собственные лимиты расходов, список разрешённых моделей и список разрешённых IP-адресов.

Подробнее: Аутентификация · Подготовка аккаунта

Файл результата и ссылка на него (asset, output URL)

Asset — это один файл, который создала задача, например изображение или видео. Output URL — веб-адрес, по которому этот файл скачивают.

В SpicyAPI: у завершённой задачи файлы перечислены в output.assets[]. У каждого есть url, по которому файл можно скачать напрямую, без API-ключа, а также expiresAt, mime (тип файла) и сведения о размере. Ссылка действует около 20 минут; чтобы получить новую, запросите задачу ещё раз. Сам файл хранится не дольше примерно 14 дней, поэтому сохраните копию всего, что вам нужно. Файл с пометкой pending: true ещё сохраняется (попробуйте снова через несколько секунд); файл с пометкой unavailable: true удалён навсегда.

Подробнее: Асинхронные задачи · Загрузка медиа и результатов

Баланс (balance)

Деньги на вашем аккаунте, из которых оплачиваются генерации.

В SpicyAPI: предоплаченный баланс в долларах США — без кредитов и баллов. Внесённые вами деньги не сгорают; у бонусных средств есть собственный срок действия. Пополняется он на странице Биллинг в консоли. GET /api/v1/chat/credit возвращает три суммы в виде текста, например "128.42": available (можно тратить), held (зарезервировано под задачи, которые ещё выполняются) и total. У некоторых аккаунтов есть также промоначисления или одобренная кредитная линия — они показываются отдельной разбивкой. Бесплатного тарифа нет: у новых аккаунтов баланс начинается с нуля.

Подробнее: Оплата · Подготовка аккаунта

Базовый URL (base URL)

Неизменная первая часть всех адресов, которыми пользуется API. Вы один раз прописываете её в коде или в настройках инструмента, а каждый запрос добавляет после неё свой путь.

В SpicyAPI: базовых URL два.

Запросы в формате Google Gemini отправляются на https://api.spicyapi.ai/v1beta. Официальные библиотеки Anthropic и Google GenAI сами добавляют часть с версией, поэтому для них указывайте просто https://api.spicyapi.ai.

Подробнее: Быстрый старт · Текст и потоковые ответы

Обратный вызов (callback)

Другое название вебхука. В SpicyAPI адрес передаётся в поле callBackUrl при создании задачи.

Каталог (catalog)

Список доступных моделей с ценами и входными данными, которые принимает каждая из них.

В SpicyAPI: у одного и того же списка есть две версии.

• Публичный каталог не требует ни аккаунта, ни ключа. Именно его показывает spicyapi.ai/explore и возвращает GET /console/v1/catalog/models. Он нужен, чтобы смотреть и сравнивать.
• Аутентифицированный каталог — GET /api/v1/models с вашим API-ключом — единственный надёжный источник сведений о том, какие модели ваш ключ может вызывать прямо сейчас и по каким ценам вашего аккаунта. Перед платной работой выбирайте элемент, у которого и enabled, и available равны true.

Команда CLI spicyapi models list, метод SDK listModels() и инструмент MCP spicyapi_models_list читают аутентифицированный каталог.

Подробнее: Модели и эндпоинты

CLI

Сокращение от command-line interface — интерфейс командной строки: программа, которой пользуются, набирая команды в терминале, а не нажимая кнопки.

В SpicyAPI: команда spicyapi, опубликованная как @spicyapi/cli, позволяет без написания кода просматривать модели, узнавать цены, создавать задачи генерации изображений и видео, дожидаться их выполнения и скачивать результаты. Деньги стоят только tasks create и tasks retry, и обе команды сначала спрашивают вас. Нужен Node.js 22.13 или новее; запустить CLI без установки можно через npx @spicyapi/cli.

Подробнее: Инструмент командной строки (CLI)

Эндпоинт (endpoint)

Один конкретный запрос, который принимает API; он обозначается HTTP-методом (например, GET, чтобы прочитать, или POST, чтобы отправить) и путём.

В SpicyAPI: например, POST /api/v1/jobs/createTask запускает генерацию, а GET /api/v1/jobs/recordInfo читает задачу. Полный адрес — это базовый URL, за которым следует путь.

Подробнее: OpenAPI и список эндпоинтов

Оболочка ответа (envelope)

Неизменная внешняя обёртка, в которую помещается каждый ответ, чтобы программа всегда знала, где что искать.

В SpicyAPI: ответы нативного API (под /api/v1) выглядят так:

{ "code": 200, "msg": "success", "data": {}, "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2" }

code — бизнес-код (200 означает успех), msg — сообщение для человека, data содержит сам ответ и при ошибке отсутствует полностью, а request_id идентифицирует этот запрос. Эндпоинты, совместимые с OpenAI, Anthropic и Gemini, вместо этого отвечают в формате своих протоколов.

Подробнее: Ошибки и повторы

Переменная окружения (environment variable)

Именованное значение, которое терминал передаёт каждой запущенной из него программе. Так программа может прочитать настройку — например, секретный ключ, — и это значение не приходится записывать ни в файл, ни в команду.

В SpicyAPI: SDK, CLI, MCP-сервер и примеры кода в этой документации читают ваш API-ключ из переменной SPICY_API_KEY. Чтобы задать её для текущего окна терминала:

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

Эта настройка забывается, когда вы закрываете окно. На странице CLI показано, как сохранить её навсегда и как проверить её, не выводя ключ целиком.

Подробнее: CLI: перед началом · Подготовка аккаунта

Код ошибки (error code)

Короткое фиксированное значение, по которому программа понимает, что пошло не так, и может отреагировать, не разбирая текст сообщения.

В SpicyAPI: кодов два вида.

• code в оболочке ответа описывает сам запрос. 200 — успех; среди остальных 400 (некорректный запрос), 401 (проблема с ключом), 40201 (недостаточно средств на балансе), 40202 (достигнут лимит расходов) и 429 (слишком много запросов). Это бизнес-код, и он точнее, чем HTTP-статус, который приходит вместе с ним.
• errorCode появляется у задачи, которая была принята, но затем завершилась ошибкой. Это одно из девяти значений: invalid_request, unsupported_combination, content_rejected, rate_limited, upstream_unavailable, generation_failed, timeout, invalid_asset или upstream_failed.

Соответствующие им сообщения, msg и errorMessage, предназначены для людей: их формулировка может меняться, и они могут приходить на выбранном вами языке. Программам следует ветвить логику только по кодам.

Подробнее: Ошибки и повторы

Резерв, списание и освобождение (hold, settle, release)

Три шага оплаты задачи. Резерв — это деньги, отложенные, но ещё не потраченные, как сумма, которую отель блокирует на вашей карте.

В SpicyAPI:

• Резерв (hold): когда задача принята, её ориентировочная стоимость (estimatedCost) откладывается с вашего баланса и отображается как held. Это ещё не списание, и это же максимум, который эта задача может стоить.
• Списание (settle): когда задача завершается успешно, с вас списывается плата за то, что она фактически израсходовала, и никогда не больше резерва. Всё, что осталось, возвращается на доступный баланс. settled: true у задачи означает, что сумма в cost окончательная.
• Освобождение (release): При ошибке или истечении срока задачи резерв обычно освобождается полностью. Некоторые отказы по содержанию оплачиваются по принятой цене, только если это исключение прямо указано на странице модели. Окончательную сумму проверяйте по settled и cost.

Подробнее: Оплата

HTTP-статус (HTTP status)

Трёхзначное число в начале каждого веб-ответа, которое в общих чертах говорит, чем закончился запрос. 2xx — всё получилось, 4xx — что-то не так с самим запросом, 5xx — проблема на сервере.

В SpicyAPI: на создание задачи приходит ответ 202 Accepted: задача принята, но это не значит, что она уже выполнена. Нативные ответы, кроме того, содержат более точный бизнес-code: например, при недостаточном балансе приходит HTTP 402 с code 40201. Выберите в своём коде что-то одно из двух для ветвления и придерживайтесь этого выбора.

Подробнее: Ошибки и повторы

Ключ идемпотентности (idempotency key)

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

В SpicyAPI: передавайте его в заголовке Idempotency-Key при создании или повторе задачи, например order-8814-render-1. Если соединение оборвалось и вы не уверены, запустилась ли задача, отправьте тот же запрос ещё раз с тем же ключом идемпотентности и тем же API-ключом в течение 24 часов: вам вернётся исходная задача, и дважды платить не придётся. Для каждой новой единицы работы используйте новый ключ. Повторное использование ключа с другим запросом отклоняется с кодом 409. Длина ключа — до 128 символов.

Подробнее: Идемпотентность

Схема входных данных (input schema)

Машиночитаемое описание того, какие поля может содержать запрос, какого типа каждое из них и какие значения допустимы.

В SpicyAPI: у каждой модели свой inputSchema, записанный в формате JSON Schema. В нём перечислены поля, которые можно передать в input, например prompt, image_url или duration_seconds, с их ограничениями и значениями по умолчанию. Сервер сверяет с ней каждый запрос, и одного неизвестного поля достаточно для ошибки 400. Песочница строит свою форму по той же схеме, а examples в каталоге — это полные наборы входных данных, которые уже прошли проверку по ней.

Подробнее: Модели и эндпоинты · Контракт Spicy Schema

JSON

Текстовый формат структурированных данных: имена и значения в фигурных скобках. Им пользуются почти все API, потому что его умеет читать любой язык программирования.

В SpicyAPI: запросы и ответы передаются в JSON. Минимальный запрос на создание задачи выглядит так:

{ "model": "MODEL_ID_FROM_CATALOG", "input": { "prompt": "A paper lantern on a rainy street at night" } }

MODEL_ID_FROM_CATALOG обозначает настоящий ID модели, взятый из актуального каталога. Денежные суммы всегда передаются текстом, например "0.008", чтобы ни одна сумма случайно не округлилась.

Подробнее: Быстрый старт

MCP

Сокращение от Model Context Protocol — открытый стандарт, который позволяет ИИ-ассистентам подключать дополнительные возможности, так называемые инструменты, из небольших программ — MCP-серверов.

В SpicyAPI: официальный сервер @spicyapi/mcp работает на вашем компьютере и даёт ассистентам вроде Claude, Cursor, VS Code или Codex 15 инструментов SpicyAPI: просматривать модели, получать расчёт стоимости, создавать задачи, загружать файлы и получать результаты. Перед запуском, повтором или уничтожением задачи всё останавливается и вас просят подтвердить действие, показывая цену, если она есть; ответить вместо вас ассистент не может. Нужен Node.js 22.13 или новее.

Подробнее: MCP-сервер

Модальность (modality)

Вид медиа, с которым работает модель.

В SpicyAPI: у каждой записи каталога есть modality, например image, video или text, и список tasks, например text-to-image или image-to-video. По ним каталог можно фильтровать, например GET /api/v1/models?modality=video&task=image-to-video.

Подробнее: Модели и эндпоинты

ID модели (model ID)

Точное имя, которое вы отправляете, чтобы выбрать модель.

В SpicyAPI: ID имеют вид publisher/model/task: кто создал модель, какая это модель и версия и что делает эндпоинт. ID эндпоинтов редактирования изображений заканчиваются на edit. Всегда копируйте ID из актуального каталога (GET /api/v1/models, spicyapi models list или listModels()), а не по памяти и не с веб-страницы: модели добавляются, ставятся на паузу и снимаются с публикации. В примерах этой документации на месте настоящего ID стоит MODEL_ID_FROM_CATALOG; если отправить сам этот заполнитель, запрос завершится ошибкой.

Подробнее: Модели и эндпоинты

Node.js

Бесплатная программа, которая выполняет JavaScript вне веб-браузера. Многие инструменты для разработчиков написаны на JavaScript, и для их работы Node.js должен быть установлен.

В SpicyAPI: SDK, CLI и MCP-серверу нужен Node.js 22.13 или новее; установщику, которым пользуется Skill, — 22.20 или новее. Установите версию LTS с nodejs.org и проверьте её в терминале командой node --version. Для Песочницы Node.js не нужен, как и в том случае, если вы вызываете API из другого языка.

Подробнее: CLI: перед началом

npm и npx

npm — менеджер пакетов, который поставляется вместе с Node.js: он скачивает и устанавливает пакеты JavaScript. npx, который идёт в комплекте, запускает пакет, не устанавливая его насовсем.

В SpicyAPI: все четыре инструмента для Node.js — это пакеты npm: @spicyapi/sdk, @spicyapi/cli, @spicyapi/mcp и @spicyapi/skill. Например, npm install @spicyapi/sdk добавляет TypeScript SDK в проект, а npx @spicyapi/cli status однократно запускает CLI без установки. SDK для Python, Go, PHP и Java ставятся средствами своих экосистем; смотрите страницу каждого из них.

Подробнее: TypeScript SDK · Инструмент командной строки (CLI)

Совместимость с OpenAI (OpenAI-compatible)

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

В SpicyAPI: текстовые модели можно вызывать через POST /v1/chat/completions и POST /v1/responses в формате OpenAI, через POST /v1/messages в формате Anthropic и через /v1beta/models/… в формате Google Gemini — везде с одним и тем же API-ключом. Направьте официальную библиотеку openai на https://api.spicyapi.ai/v1. Любая текстовая модель работает с любым из этих форматов. Эти эндпоинты берут цену, действующую в момент приёма запроса, и не принимают расчёт стоимости, поэтому задайте для ключа лимиты расходов.

Подробнее: Текст и потоковые ответы

Песочница (Playground)

Форма на сайте, где можно попробовать модель: заполнить поля и нажать кнопку, не написав ни строчки кода.

В SpicyAPI: на странице каждой модели на spicyapi.ai есть вкладка Песочница. Заполнить форму и посмотреть, какой запрос она составит, можно без аккаунта; чтобы запустить его, нужно войти и иметь деньги на балансе. Перед каждым запуском показывается ориентировочная стоимость, запуск оплачивается так же, как вызов API, и появляется в разделе Логи консоли.

Подробнее: Как устроен SpicyAPI

Опрос (polling)

Многократные вопросы серверу, закончилось ли что-то, вместо того чтобы ждать, пока вам сообщат.

В SpicyAPI: задачу опрашивают запросом GET /api/v1/jobs/recordInfo?taskId=…, пока её состояние не перестанет быть queued или running. Подождите 2–3 секунды перед первой проверкой, делайте каждую следующую паузу примерно в 1,5 раза длиннее — до 10–15 секунд — и прекращайте ждать к выбранному вами сроку. Прекращение ожидания не останавливает задачу. Опрос расходует ваш лимит запросов, поэтому в рабочей среде лучше использовать вебхук.

Подробнее: Асинхронные задачи

Уничтожение содержимого (purge)

Безвозвратное удаление сохранённого содержимого по запросу, не дожидаясь, пока истечёт срок его хранения.

В SpicyAPI: POST /api/v1/jobs/purge (а также Уничтожить результаты в разделе «Логи» консоли, spicyapi tasks purge, purgeTask()) удаляет созданные файлы завершённой задачи, её результат и текст промпта во входных данных. Платёжная запись остаётся: сумма, модель, состояние, временные метки и request_id. Уничтожение — это не отмена, оно ничего не возвращает и необратимо. Работает только для задач, которые уже завершились.

Подробнее: Хранение и удаление данных

Расчёт стоимости (quote)

Цена, заранее вычисленная для одного конкретного запроса.

В SpicyAPI: POST /api/v1/jobs/quote принимает то же тело, которое вы бы отправили, и возвращает estimatedCost, maxCharge и expiresAt, не создавая задачу и не резервируя деньги. Расчёт бесплатен и действует пять минут. Если вы отправляете запрос с полученными quoteId и expectedCost, а запрос или цена изменились, отправка отклоняется с кодом 40901, а не оплачивается по другой сумме. CLI и MCP-сервер автоматически получают расчёт перед созданием задачи.

Подробнее: Расчёт цены и совместимость

Лимит запросов (rate limit)

Ограничение на количество запросов, которые можно отправить за определённый промежуток времени, чтобы одна вышедшая из-под контроля программа не перегрузила сервис.

В SpicyAPI: нативный API по умолчанию допускает 1000 запросов за 10 секунд на аккаунт; отдельно для чтения и столько же для записи, и каждый из двух лимитов общий для всех ключей аккаунта. Опрос считается чтением, поэтому даже частый опрос не мешает отправлять задачи. При превышении приходит 429 с заголовком Retry-After, где указано, сколько секунд подождать. Лимит считает запросы, а не задачи: уже выполняющиеся задачи его не расходуют.

Подробнее: Лимиты запросов

request_id

Идентификатор, который сервер присваивает одному запросу, чтобы этот запрос потом можно было найти в журналах.

В SpicyAPI: каждый нативный ответ — и при успехе, и при ошибке — содержит request_id (например, req_01k3…), который также передаётся в заголовке X-Request-Id. Сохраняйте его в своих логах и указывайте при обращении в поддержку. В вебхуке версии 2 request_id вместо этого идентифицирует доставку (whd_…) и не меняется при повторных попытках доставки.

Подробнее: Ошибки и повторы · Webhook

Хранение (retention)

Сколько сохранённые данные хранятся, прежде чем их удалят.

В SpicyAPI:

Сократить срок хранения созданных файлов, загрузок и текста промптов можно на странице Защита данных в консоли или для отдельной задачи — заголовком X-Spicy-Retention, а уничтожить содержимое в любой момент — через purge. Никакая настройка не делает срок длиннее.

Подробнее: Хранение и удаление данных

SDK

Сокращение от software development kit — набор для разработки: готовая библиотека кода, которую вы подключаете к своей программе, чтобы не собирать каждый запрос вручную.

В SpicyAPI: официальных SDK пять — @spicyapi/sdk для TypeScript и JavaScript на Node.js и по одному для Python, Go, PHP и Java. Каждый берёт на себя ключ, ожидание задач, повторы, загрузку файлов и проверку вебхуков, так что пара вызовов проводит задачу от отправки до результата. Все они работают только на серверах — не в браузерах и не в мобильных приложениях — и ни один не охватывает чат-модели.

Подробнее: TypeScript SDK · Python SDK · Go SDK · PHP SDK · Java SDK

Подпись (signature, HMAC)

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

В SpicyAPI: каждая доставка вебхука содержит заголовок X-Webhook-Signature — HMAC-SHA256 от ID задачи, времени доставки и хеша точного тела запроса, вычисленный с вашим ключом подписи вебхука. Этот ключ создаётся и меняется на странице Вебхуки в консоли и показывается только в этот момент; если вы его не скопировали, смените его там. Проверяйте подпись, прежде чем доверять доставке, — с помощью verifyWebhook из SDK или spicyapi webhooks verify — и отклоняйте доставки, чья метка времени отличается от текущего времени больше чем на пять минут.

Подробнее: Webhook

Лимит расходов (spend cap)

Потолок расходов, который вы задаёте заранее, чтобы ошибка или утёкший ключ не могли израсходовать весь баланс.

В SpicyAPI: для каждого API-ключа можно самостоятельно задать дневной, месячный и общий лимит в долларах США, а у новых ключей лимита нет, пока вы его не добавите. Команды могут добавить дневной и месячный бюджет, а у платформы есть собственный дневной лимит. Задача, которая превысила бы любой из них, отклоняется с кодом 40202 ещё до запуска, и ничего не списывается. Дневные лимиты обнуляются в 00:00 UTC, месячные — 1-го числа месяца; общие не обнуляются никогда. Значение 0 означает, что на этом уровне лимита нет.

Подробнее: Оплата · Аутентификация

Потоковая передача (streaming, SSE)

Передача ответа по частям, по мере того как он создаётся, через одно открытое соединение, а не целиком в самом конце. SSE (server-sent events, события, отправляемые сервером) — распространённый веб-формат для этого.

В SpicyAPI: текстовые модели могут передавать ответ потоком, слово за словом, через совместимые эндпоинты (например, stream: true в /v1/chat/completions) или через нативный POST /api/v1/jobs/stream. Каждый протокол по-своему обозначает конец потока. Если закрыть соединение раньше времени, текст перестанет к вам приходить, но модель не остановится, и израсходованное всё равно будет оплачено. Потоковый текст не сохраняется, поэтому позже получить его снова нельзя.

Подробнее: Текст и потоковые ответы

Задача (task)

Одна единица работы, которая выполняется в фоне: вы её передаёте, а результат забираете позже.

В SpicyAPI: каждая генерация изображения или видео — это задача. POST /api/v1/jobs/createTask принимает её и возвращает ID задачи, начинающийся с job_; затем вы опрашиваете задачу или получаете вебхук, когда она завершится. Через API задачу можно прочитать только тем же API-ключом, которым она создана; на странице Логи в консоли видны все задачи вашего аккаунта. Принятую задачу отменить нельзя.

Подробнее: Асинхронные задачи · Необратимость и повтор

Состояние задачи (task state)

На каком этапе своего жизненного цикла находится задача.

В SpicyAPI:

В старых записях может встретиться также canceled; новые задачи в это состояние никогда не переходят. Считайте любое состояние, кроме queued и running, конечным.

Подробнее: Асинхронные задачи

Терминал (terminal)

Текстовое окно, в котором вы набираете команды и запускаете их клавишей Enter. В macOS это приложение Терминал (Terminal); в Windows используйте PowerShell; в большинстве графических окружений Linux терминал открывается сочетанием Ctrl + Alt + T. Не путайте его с конечным состоянием (terminal state).

В SpicyAPI: терминал нужен, чтобы запускать CLI, устанавливать инструменты на Node.js, такие как MCP-сервер или Skill, и пробовать примеры curl из этой документации.

Подробнее: CLI: перед началом

Конечное состояние (terminal state)

Итоговое состояние: когда задача его достигла, оно больше никогда не меняется.

В SpicyAPI: конечным является любое состояние задачи, кроме queued и running: succeeded, failed, expired и, в старых записях, canceled. Проверяйте условие «не queued и не running», а не перечисляйте итоговые состояния, — тогда код продолжит работать, если появится новое. Вебхуки отправляются только тогда, когда задача достигает конечного состояния. Уничтожить содержимое можно только у завершённых задач, а повторить — задачи в состоянии failed или expired.

Подробнее: Асинхронные задачи

Загрузка файла (upload)

Отправка файла с вашего компьютера на сервер, чтобы им можно было там воспользоваться.

В SpicyAPI: модель, которая принимает на вход изображение, видео или аудио, может получить его тремя способами: по публичной HTTPS-ссылке на файл, в виде небольшого изображения, встроенного прямо в запрос как data URI (до 1 MiB), или как загруженный файл. Загрузка проходит в три шага: запросить билет (POST /api/v1/common/upload-url), отправить файл по адресу из билета, затем подтвердить загрузку (POST /api/v1/files/{fileId}/commit). Подтверждение возвращает адрес spicy://, который нужно указать в поле входных данных модели. Им можно пользоваться один день. Изображения — до 10 MiB, аудио и видео — до 90 MiB и 600 секунд. uploadFile() в SDK, spicyapi files upload и MCP-сервер выполняют все три шага за вас.

Подробнее: Загрузка медиа и результатов

Вебхук (webhook)

Адрес на вашем собственном сервере, к которому другой сервис обращается, когда что-то происходит, — так вам не нужно постоянно спрашивать самому. Его также называют обратным вызовом (callback).

В SpicyAPI: укажите публичный HTTPS-адрес в callBackUrl при создании задачи. Когда задача достигнет конечного состояния, SpicyAPI отправит туда запрос POST с тем же содержимым, которое вернул бы recordInfo, подписанный вашим ключом подписи вебхука. Ответьте любым статусом 2xx в течение 15 секунд; иначе доставка повторяется — до восьми попыток примерно за девять часов, — а отправить её заново можно со страницы «Вебхуки» в консоли. Уведомления о том, что задача просто запустилась, не бывает. Локальные адреса вроде http://localhost:3000 принимать вебхуки не могут, поэтому, пока вы разрабатываете на своём компьютере, пользуйтесь опросом.

Подробнее: Webhook

Рабочее пространство и команда (workspace, team)

Общее пространство, в котором несколько человек пользуются одними и теми же ключами, задачами и бюджетами в рамках одного аккаунта.

В SpicyAPI: у командного рабочего пространства есть участники с ролями owner, admin, developer, billing и readonly. Все участники видят сводку по задачам и расход; owner, admin и developer видят также входные данные и результаты задач. Новые задачи команды оплачиваются с аккаунта владельца, а участники никогда не видят личный баланс и платежи владельца. Команды могут задавать дневной и месячный бюджет.

Подробнее: Консоль и рабочие пространства