Интеграция в рабочей среде

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

Выберите модель и протокол

• Выберите модель, которую ваш ключ действительно может вызывать. Вызовите GET /api/v1/models со своим API-ключом и используйте только модели, у которых и enabled, и available равны true. Из того же ответа прочитайте inputSchema модели (список полей, которые она принимает) и examples. Страница модели на сайте рассказывает, что модель умеет, но не доказывает, что ваш ключ может вызвать её прямо сейчас. См. Модели и эндпоинты.
• Используйте правильную точку входа. Задачи с изображениями, видео и другими медиа идут через API задач под /api/v1 (createTask, затем recordInfo или обратный вызов). Текстовые модели можно вызывать также через клиенты, совместимые с OpenAI или Anthropic, под /v1 или через клиенты, совместимые с Gemini, под /v1beta. См. Текст и потоковые ответы.
• Аутентифицируйтесь только API-ключом. Файл cookie, полученный при входе в консоль, — это не учётные данные для API, и копировать его в код нельзя ни в коем случае.

Защитите ключи и баланс

• Держите ключ на своём сервере. Храните его в переменной окружения (SPICY_API_KEY) на серверной стороне и никогда — в коде для браузера, в мобильных приложениях или в публичном репозитории. См. Аутентификация.
• Отдельный ключ для каждого окружения и сервиса. Называйте каждый ключ по тому, что им пользуется (например, «production-worker»), чтобы можно было отозвать один, не останавливая остальные.
• Задайте ограничения для рабочего ключа: дневной лимит, рассчитанный на неудачный день, месячный бюджет, разрешённые модели и — для вызовов с сервера — список разрешённых IP. См. ограничения для отдельного ключа. При редактировании ключа помните, что пустое поле лимита означает отсутствие ограничения.
• Проверьте сроки действия. Ключ со сроком действия перестаёт работать в конце этого дня (UTC) и возвращает тот же 401, что и отозванный ключ. Занесите дату в календарь или не задавайте срок для долгоживущей серверной части.
• Не останьтесь без денег посреди пакетной обработки. Задача, отклонённая из-за нехватки баланса, возвращает 40201 и в очередь не попадает. Включите Оповещение о низком балансе в разделе «Уведомления» и подумайте об автопополнении.
• Лимиты команды тоже действуют. Если ваш ключ принадлежит команде, дневной и месячный лимит команды могут остановить задачи с кодом 40202, даже когда собственные лимиты ключа не достигнуты, а каждая задача оплачивается с баланса владельца команды. См. лимиты расходов.
• Спланируйте смену ключа подписи вебхуков. При смене ключа в консоли нет переходного периода: старый ключ сразу перестаёт подписывать. Доставки, которые ещё повторяются, подписываются новым ключом. Меняйте ключ в спокойное время, сразу разверните новый ключ в своём обработчике и восстановите всё пропущенное через recordInfo. См. Webhook.

Готовьте входные данные на своём сервере

• Проверяйте данные по актуальной схеме. Соблюдайте типы полей, допустимые значения и условные требования из inputSchema и проверяйте данные заново после смены модели — у каждой модели своя схема.
• Передавайте медиа поддерживаемым способом. Используйте публично доступный URL https:// или поддерживаемый ввод в Base64. Для локальных файлов запросите URL для загрузки, отправьте байты запросом PUT, вызовите files/{fileId}/commit, а затем передайте полученный URI spicy:// в поле входных данных модели. См. Загрузка медиа и результатов.
• Используйте каждый загруженный файл, пока он действителен. URI spicy:// работает до момента expiresAt из ответа на commit (по умолчанию 1 день). Не запрашивайте пачками URL для загрузки, которые не будете использовать, — неиспользованные засчитываются в лимит. См. Лимиты запросов.

Получите расчёт стоимости, прежде чем соглашаться на списание

• Показывайте цену до того, как тратить деньги. Отправьте полные model, input и callBackUrl в POST /api/v1/jobs/quote. Покажите тому, кто платит, estimatedCost, maxCharge, валюту (USD) и expiresAt. Расчёт стоимости бесплатен: он не создаёт задачу и не резервирует средства.
• Отправляйте ровно то, что подтвердили. Расчёт действует пять минут. После подтверждения отправьте тот же запрос в createTask, добавив quoteId и expectedCost.
• Обрабатывайте 40901. Этот код означает, что с момента расчёта истёк его срок, изменились входные данные или изменилась цена. Получите новый расчёт и покажите новую сумму; никогда не соглашайтесь молча на более высокую. См. Расчёт цены и совместимость.
• Считайте деньги точно. Суммы передаются десятичными строками, например "0.008". Храните и складывайте их с помощью десятичной арифметики, а не чисел с плавающей точкой. См. Оплата.

Сохраняйте бизнес-операцию

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

• До отправки сохраните: ID своего заказа или операции, краткое описание запроса без секретов и полных промптов (достаточное, чтобы потом его узнать) и Idempotency-Key, который вы отправите.
• После приёма сохраните: taskId и request_id из ответа.
• Используйте тот же ключ для той же отправки. Отправляйте исходный Idempotency-Key повторно для того же аккаунта, API-ключа и запроса в течение 24 часов — вам вернётся исходная задача вместо второго списания. См. Идемпотентность.
• Считайте тайм-аут «неизвестным исходом», а не «ошибкой». Прежде чем решать, создавать ли новую задачу, восстановите исходную отправку с её ключом. См. Диагностика и восстановление.
• Знайте, во что обходится повтор. Повтор задачи, которая уже завершилась ошибкой, создаёт новую задачу на текущих условиях и по текущим ценам.

Надёжно обрабатывайте обратные вызовы и результаты

• Проверяйте каждый обратный вызов. До разбора JSON проверьте подпись и метку времени по исходным байтам запроса, затем удалите дубликаты и сохраните событие. См. Webhook.
• Подтверждайте приём быстро. Сразу отвечайте 2xx, а долгую работу выполняйте в собственной очереди.
• Ожидайте дубликатов и задержек. Решайте, что делать, по state задачи, а не по порядку, в котором приходят обратные вызовы.
• Оставьте опрос как запасной вариант. Если обратный вызов задерживается, читайте recordInfo с растущими паузами, а не каждую секунду.
• Смотрите на правильный сигнал. HTTP 202 от createTask означает, что задача принята. state: "succeeded" означает, что генерация завершена. settled: true означает, что списание окончательное.

Ограничьте параллельность и сохраняйте результаты

• Ограничьте число одновременно выполняющихся задач на аккаунт и задайте сроки своим собственным запросам. Каждая принятая задача держит средства в резерве, пока по ней не пройдёт окончательное списание.
• Соблюдайте Retry-After при 429 и не допускайте, чтобы множество клиентов синхронно опрашивали сервис каждую секунду. См. Лимиты запросов.
• Кешируйте данные каталога ненадолго и только приватно и никогда не считайте расчёт стоимости постоянным прайс-листом.
• Архивируйте результаты, которые нужно сохранить. Ссылки на скачивание действуют 20 минут; созданные медиафайлы хранятся не дольше примерно 14 дней, а загрузки — один день. Эти сроки можно сократить или удалить содержимое задачи раньше через POST /api/v1/jobs/purge. Сокращение срока хранения может удалить и результаты задач, которые вы уже выполнили, — см. Хранение и удаление данных.
• Не рассчитывайте остановить работу разрывом соединения. Принятая задача продолжает выполняться, и отменить её нельзя.

Проверьте всё перед запуском

Начните с бесплатных вызовов: каталог (GET /api/v1/models), баланс (GET /api/v1/chat/credit) и расчёт стоимости. Затем проведите одну небольшую настоящую генерацию через собственный процесс подтверждения стоимости — она оплачивается как любая другая задача. Убедитесь, что ваша интеграция справляется с каждым из этих сценариев:

Записывайте в журнал request_id, taskId, время, state и суммы. Не допускайте, чтобы API-ключи и полные промпты попадали в общие логи.

Связанные разделы

Расчёт цены и совместимость протоколов · Модели и эндпоинты · Загрузка медиа и результатов · Webhook · Ошибки и повторы · Диагностика и восстановление · Оплата · Хранение и удаление данных