Как устроен SpicyAPI

Если вы здесь впервые, начните с этой страницы. Она простыми словами объясняет, что делает SpicyAPI, помогает выбрать подходящий вам способ работы и знакомит с небольшим набором понятий, которые остальная документация считает уже известными. Уметь программировать, чтобы её прочитать, не нужно.

Что такое SpicyAPI

SpicyAPI даёт один API-ключ к моделям для изображений, видео и текста от множества разных разработчиков и берёт плату за каждое использование в долларах США.

Без него, чтобы работать с несколькими ИИ-моделями, пришлось бы открывать аккаунт в каждой компании, разбираться в формате запросов каждой из них и пополнять каждый счёт отдельно. В SpicyAPI у вас один аккаунт и один баланс. Вы выбираете модель, отправляете промпт (и референсное изображение, если модель его принимает) и получаете обратно изображение, видео или текст. Если перейти на другую модель, порядок отправки запроса и получения результата останется прежним.

• Один ключ — много моделей. Все модели изображений и видео работают одинаково: вы отправляете задачу, а затем забираете результат. Текстовые модели вдобавок принимают запросы в форматах официальных библиотек OpenAI, Anthropic и Google Gemini.
• Оплата за использование, в долларах. В зависимости от модели цена указана за изображение, за секунду видео, за запрос или за токен. Подписки нет, системы кредитов или баллов тоже нет: цена, которую вы видите, — это ровно та сумма в долларах, которая спишется с баланса. Бесплатного тарифа тоже нет, поэтому перед первой генерацией баланс нужно пополнить. См. раздел Оплата.
• Когда задача принята, её ориентировочная стоимость резервируется на вашем балансе. Если задача завершилась успешно, вы платите за то, что она фактически израсходовала, и никогда не больше этой суммы. При ошибке или истечении срока задачи резерв обычно освобождается полностью. Некоторые отказы по содержанию оплачиваются по принятой цене, только если это исключение прямо указано на странице модели. Окончательную сумму проверяйте по settled и cost.
• Никаких переключателей режима контента. SpicyAPI не требует в запросе флага режима контента и не проверяет содержимое каждого запроса. Что получится, зависит от самой модели: некоторые модели отклоняют отдельные запросы или смягчают результат. Ответственность за то, как вы используете созданное, остаётся на вас; см. Контент и ответственность за использование.

SpicyAPI не обслуживает материковый Китай; ограничения действуют и ещё в нескольких регионах — подробности на той же странице правил.

Что можно создавать

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

Чтобы посмотреть текущие модели с картинками, описаниями и ценами, откройте spicyapi.ai/explore. Тот же список можно получить и без аккаунта и ключа — в виде «сырого» JSON, если хотите заглянуть в него из терминала:

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

Команда выведет длинный блок текста. У каждой модели в нём есть modality (image, video или text), список tasks и начальная цена price. Этот публичный список нужен для знакомства; когда у вас появится ключ, список моделей, которые ваш ключ действительно может вызывать, выдаёт GET /api/v1/models. См. статью Каталог в глоссарии.

Выберите свой путь

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

Попробовать в браузере

• Кому и зачем: всем, кто хочет увидеть, на что способна модель, прежде чем что-то решать. Ничего не нужно устанавливать, код не нужен.
• Что понадобится: веб-браузер. Открыть любую модель и заполнить её форму можно и без аккаунта. Чтобы нажать Запустить, нужно войти в аккаунт и иметь деньги на балансе.
• Это стоит денег? Каждый запуск оплачивается так же, как вызов API. При ошибке или истечении срока задачи резерв обычно освобождается полностью. Некоторые отказы по содержанию оплачиваются по принятой цене, только если это исключение прямо указано на странице модели. Окончательную сумму проверяйте по settled и cost.
• С чего начать: откройте spicyapi.ai/explore, выберите модель и перейдите на её странице на вкладку Песочница. Завершённые запуски появляются также в разделе Логи в консоли.

Поручить ИИ-ассистенту

• Кому и зачем: тем, кто уже работает с ИИ-ассистентом — Claude, Cursor, VS Code, Codex, Windsurf или Gemini CLI — и хочет просматривать модели, сравнивать цены и генерировать изображения или видео прямо в переписке. Разработчики тоже пользуются этим способом, чтобы разобраться, прежде чем писать код.
• Что понадобится: Node.js 22.13 или новее, API-ключ и приложение-ассистент с поддержкой MCP. Платные действия работают только в приложениях, которые умеют показать вам вопрос с подтверждением.
• Это стоит денег? Просмотр моделей, расчёт стоимости и получение результатов бесплатны. Перед запуском или повтором генерации всё останавливается и вам показывают цену; ответить на этот вопрос вместо вас ассистент не может.
• С чего начать: MCP-сервер даёт ассистенту действия SpicyAPI. Agent Skill учит ИИ-ассистента для программирования писать интеграции со SpicyAPI безопасным способом и хорошо работает в паре с сервером.

Вводить команды в терминале

• Кому и зачем: чтобы сравнивать цены, генерировать изображения и видео на своём компьютере и сохранять файлы, повторять однотипную работу или запускать простой скрипт. Программировать не нужно.
• Что понадобится: терминал, Node.js 22.13 или новее и API-ключ, сохранённый в переменной окружения SPICY_API_KEY.
• Это стоит денег? Списать деньги могут только spicyapi tasks create и spicyapi tasks retry, и обе команды спрашивают разрешения до любого списания.
• С чего начать: Инструмент командной строки (CLI).

Строить рабочие процессы из узлов в ComfyUI

• Кому и зачем: тем, кто уже работает в ComfyUI и хочет использовать облачные модели рядом со своими локальными узлами: передать результат модели изображений в модель видео, добавить звуковую дорожку или поручить текстовой модели написать промпт.
• Что понадобится: ComfyUI на вашем компьютере или сервере и API-ключ. Модели SpicyAPI работают на наших серверах, поэтому видеокарта для них не нужна.
• Это стоит денег? Каждый запуск оплачивается так же, как вызов API. Каждый узел показывает свою цену, оценивает стоимость до запуска и может остановить любой запуск дороже заданного вами лимита.
• С чего начать: Узлы ComfyUI.

Писать код

• Кому и зачем: чтобы добавить генерацию изображений, видео или текста в собственное приложение, серверную часть сайта или конвейер обработки данных.
• Что понадобится: код, который работает на сервере или на вашем компьютере, потому что API-ключ ни в коем случае нельзя размещать на веб-странице или в мобильном приложении. Официальные SDK есть для TypeScript (Node.js 22.13 или новее), Python 3.11+, Go 1.23+, PHP 8.1+ и Java 17+; из любого другого языка можно обращаться к HTTP API напрямую.
• Это стоит денег? Оплачивается каждая принятая генерация. Расчёт стоимости, чтение каталога и просмотр задач бесплатны.
• С чего начать: TypeScript SDK для Node.js — или SDK для Python, Go, PHP и Java. Для обычного HTTP с примерами на curl, Node.js, Python и Go берите Быстрый старт; чат-модели описаны на странице Текст и потоковые ответы, а полный разобранный пример — в пошаговом руководстве «Изображение в видео».

Понятия, которые встречаются везде

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

Что происходит, когда вы что-то генерируете

1. Вы выбираете модель и заполняете её входные данные.
2. При желании запрашиваете расчёт стоимости: точную цену, бесплатно.
3. Вы отправляете запрос. SpicyAPI принимает его как задачу, выдаёт ID задачи и резервирует на балансе её ориентировочную стоимость.
4. Модель работает в фоне. Изображения обычно готовы за секунды, видео часто занимает минуты.
5. Задача завершается. Если она выполнена успешно, вы платите за то, что она фактически израсходовала, и никогда не больше зарезервированной суммы. При ошибке или истечении срока задачи резерв обычно освобождается полностью. Некоторые отказы по содержанию оплачиваются по принятой цене, только если это исключение прямо указано на странице модели. Окончательную сумму проверяйте по settled и cost.
6. Вы забираете результат — либо SpicyAPI сам обращается к вашему серверу, либо вы спрашиваете сами — и скачиваете файл. Ссылки на скачивание временные, а файлы хранятся ограниченное время, поэтому сохраните то, что хотите оставить.

ID модели

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

Задачи и их состояния

Генерация изображений и видео асинхронна: отправка запроса и получение результата — это два отдельных шага, которые связывает ID задачи, начинающийся с job_. Задача переходит из queued в running и завершается состоянием succeeded, failed или expired; любое состояние, кроме queued и running, окончательное. Текстовые модели, напротив, отвечают в том же соединении, часто слово за словом. Асинхронные задачи · Текст и потоковые ответы · Глоссарий: состояние задачи

Расчёт стоимости

Расчёт стоимости оценивает именно ваш запрос, ничего не запуская и не резервируя деньги. Он действует пять минут. Если вы отправите запрос с этим расчётом, а цена или сам запрос за это время изменились, отправка будет отклонена, а не оплачена по другой цене. Расчёт цены и совместимость · Глоссарий: расчёт стоимости

Ключ идемпотентности

Метка, которую вы сами придумываете для одной единицы работы и отправляете вместе с ней. Если соединение оборвалось и вы в течение 24 часов снова отправляете тот же запрос с той же меткой и тем же API-ключом, вам вернётся исходная задача, а не запустится вторая, за которую пришлось бы заплатить ещё раз. CLI и MCP-сервер создают такую метку сами; при работе через SDK или напрямую по HTTP вы передаёте свою. Идемпотентность · Глоссарий: ключ идемпотентности

Обратные вызовы

Вместо того чтобы снова и снова спрашивать, завершилась ли задача, можно передать ей callBackUrl — публичный HTTPS-адрес на вашем сервере. Когда задача завершится, SpicyAPI отправит результат туда, с подписью, по которой можно проверить, что он действительно пришёл от SpicyAPI. Многократно спрашивать самому — это называется опросом (polling) — вполне нормально, пока вы тестируете на своём компьютере. Webhook · Глоссарий: вебхук

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

Ссылка на скачивание результата действует около 20 минут; чтобы получить новую, запросите задачу ещё раз. Созданные файлы хранятся не дольше примерно 14 дней, загруженные файлы — один день, текст промптов — 30 дней; все три срока можно сократить, а содержимое отдельной задачи — уничтожить по запросу. Платёжные записи хранятся гораздо дольше. Скачайте всё, что хотите оставить. Хранение и удаление данных · Глоссарий: хранение

Баланс и лимиты расходов

Ваш баланс — это предоплаченные доллары США. Для каждого API-ключа можно также самостоятельно задать дневной, месячный и общий лимит расходов. Если баланса не хватает на задачу, вы получите ошибку 40201; если достигнут лимит — 40202. Ни в том, ни в другом случае задача не создаётся и ничего не списывается. Оплата · Аутентификация · Глоссарий: лимит расходов

Первый раз по порядку

Где получить помощь

• Быстрые ответы: Частые вопросы, Глоссарий, Диагностика и восстановление и Ошибки.
• Работает ли сервис? status.spicyapi.ai.
• Написать нам: начните диалог на странице Поддержка в консоли или воспользуйтесь страницей контактов. Укажите request_id или ID задачи и время по UTC. Никогда не отправляйте свой API-ключ.

Что дальше