OpenAPI и указатель эндпоинтов
Контракт OpenAPI 3.1, все публичные эндпоинты и руководства, общие заголовки запросов и адрес производственного API.
Машиночитаемый публичный контракт доступен как OpenAPI 3.1 YAML. Используйте его для создания клиента или проверки интеграции по действующим публичным эндпоинтам.
Адрес производственного API
https://api.spicyapi.ai — единственный производственный адрес в OpenAPI servers[0].url. API задач использует /api/v1, совместимые протоколы — /v1 и /v1beta.
Эти API позволяют выбирать модель, оценивать стоимость и отслеживать расходы без консоли. Каталог включает цены аккаунта; при зависимости цены от параметров рассчитывайте точный ввод. История задач и использование ограничены вызывающим API-ключом. Создание, ротация ключей и бюджеты остаются в консоли. Каждая таблица ссылается на полное руководство эндпоинта.
Поиск моделей, цены и API аккаунта
| Метод | Путь | Назначение | Руководство |
|---|---|---|---|
GET | /console/v1/catalog/models | Публичный каталог оценки: без ключа, стандартные цены, ограничение по адресу источника | Быстрый старт |
GET | /api/v1/models | Доступные для вызова модели, цены аккаунта и дополнительные схемы | Каталог моделей |
GET | /api/v1/models/{model} | Одна модель с полной JSON Schema | Каталог моделей |
POST | /api/v1/jobs/quote | Расчёт точного запроса на пять минут без задачи и резервирования средств | Расчёт цены |
GET | /api/v1/chat/credit | Доступный, зарезервированный и общий баланс | Оплата |
GET | /api/v1/usage | Вызовы текущего ключа и рассчитанные расходы USD по дате и модели | Оплата |
API генерации и задач
| Метод | Путь | Назначение | Руководство |
|---|---|---|---|
GET | /api/v1/jobs | История задач текущего ключа с курсорной пагинацией | Задачи |
POST | /api/v1/jobs/createTask | Создание асинхронной задачи генерации | Задачи |
GET | /api/v1/jobs/recordInfo | Чтение задачи, созданной вызывающим ключом | Задачи |
POST | /api/v1/jobs/retry | Новая задача из неудачной или истёкшей; исторические отменённые совместимы | Действия задач |
POST | /api/v1/jobs/purge | Уничтожение файлов и промпта терминальной задачи без изменения оплаты | Хранение |
POST | /api/v1/jobs/stream | Запуск текстовой модели с потоком SSE | Текст и поток |
API медиа
| Метод | Путь | Назначение | Руководство |
|---|---|---|---|
POST | /api/v1/common/upload-url | Получение разрешения прямой загрузки медиа | Медиа |
POST | /api/v1/files/{fileId}/commit | Проверка и подтверждение загрузки с возвращением готового для задачи URI spicy:// | Медиа |
POST | /api/v1/files/import | Импорт файла весов LoRA по ссылке с необязательным токеном доступа, который используется один раз и не сохраняется; возвращает готовый для задачи URI spicy:// | Веса адаптера |
POST | /api/v1/common/download-url | Короткоживущий URL результата (необязательно: завершённая задача уже содержит его) | Медиа |
POST | /api/v1/assets | Сохранить файл в библиотеку ассетов (Idempotency-Key обязателен) | Медиа |
GET | /api/v1/assets | Список сохранённых ассетов (фильтры favorite, collectionId, q; сортировка sort) | Медиа |
GET | /api/v1/assets/usage | Тариф, использование и лимиты библиотеки ассетов | Медиа |
GET | /api/v1/assets/{assetId} | Получить один ассет с новой приватной ссылкой предпросмотра | Медиа |
PATCH | /api/v1/assets/{assetId} | Переименовать ассет или изменить флаг favorite | Медиа |
DELETE | /api/v1/assets/{assetId} | Удалить ассет | Медиа |
GET | /api/v1/assets/entities | Список персонажей в библиотеке ассетов (только чтение) | Медиа |
GET | /api/v1/assets/entities/{entityId} | Один персонаж с изображениями по порядку (только чтение) | Медиа |
Аутентификация и оболочки ответов
Все эндпоинты кроме публичного каталога требуют ключ в Authorization: Bearer sk-spicy-…; совместимые (/v1, /v1beta) также принимают x-api-key SDK Anthropic и x-goog-api-key SDK Google GenAI. Ключ в строке URL никогда не принимается. Задачи, повторы, уничтожение и ссылки доступны только создавшему задачу ключу; см. Аутентификация.
JSON API задач имеет общую оболочку {code,msg,data,request_id}; совместимые эндпоинты используют собственные протоколы. Итог задачи выражен data.state, а не внешним code. См. Ошибки.
Общие заголовки запросов
| Заголовок | Куда отправляется | Назначение |
|---|---|---|
Authorization: Bearer … | Всё кроме публичного каталога | Ваш API-ключ |
Idempotency-Key | jobs/createTask, jobs/retry, jobs/stream, POST /v1/videos и текстовые эндпоинты /v1 и /v1beta | Безопасный повтор после сетевой ошибки. Задачи возвращают исходную задачу; текст предотвращает второе списание, но не возвращает потерянный ответ. См. Идемпотентность |
X-Spicy-Retention | jobs/createTask, jobs/stream | Сокращает хранение результатов и промпта этой задачи в секундах. См. Хранение |
Accept-Language | Любой | Язык ошибок; коды неизменны. См. Ошибки |
Использование OpenAPI
- Пробуйте запросы без кода: импортируйте файл OpenAPI сверху страницы в Postman, Insomnia или Bruno и задайте bearer token своим ключом. Помните, создание задач платное.
- Создайте клиента: передайте тот же файл генератору OpenAPI 3.1 своего языка.
Изменения контракта
- Не храните параметры моделей постоянным жёстким снимком; читайте
inputSchemaиз/models/{model}. - Допускайте неизвестные поля ответа, но не угадывайте поля запроса.
- До выпуска включайте OpenAPI YAML в создание кода или контрактные тесты.
Совместимые эндпоинты
| Метод | Путь | Протокол |
|---|---|---|
GET | /v1/models | Models |
POST | /v1/chat/completions | Chat Completions |
POST | /v1/responses | Responses |
POST | /v1/messages | Messages |
POST | /v1beta/models/{model}:generateContent | Gemini generateContent |
POST | /v1beta/models/{model}:streamGenerateContent | Gemini streamGenerateContent |
POST | /v1/videos | Videos |
GET | /v1/videos/{videoId} | Состояние видео |
GET | /v1/videos/{videoId}/content | Содержимое видео |
Текстовые эндпоинты описаны в Текст и поток, оплата — в Расчёт и совместимость.
Официальный пакет TypeScript — @spicyapi/sdk. Для Python и Go или без дополнительной зависимости приведённые ниже копируемые эталонные клиенты вызывают эндпоинты только средствами языка. Python выполняет весь медиапроцесс: загружает и подтверждает референс, проверяет цену расчётом, создаёт задачу и опрашивает до терминального состояния, читает файлы или текст, обновляет истёкшую ссылку, уничтожает содержимое и проверяет подпись webhook. Go охватывает тот же пайплайн с context каждого вызова и типизированной ошибкой для errors.As. TypeScript предоставляет создание, повтор, чтение и ограниченное ожидание; для загрузок и остального API Node.js используйте SDK.
Копируемые эталонные клиенты
Примеры без сторонних зависимостей: поиск моделей, создание задач, повторный запуск завершившихся ошибкой задач, чтение всех конечных состояний, ограниченное ожидание, идемпотентность и ошибки. Принятую задачу отменить нельзя.
Это примеры документации, а не опубликованные пакеты npm и PyPI или модули Go. Десять минут — локальный предел, не производственный SLA.
