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

Что такое CLI

spicyapi — небольшая программа, которую запускают в терминале: это окно, где вместо нажатия кнопок вводят команды. Каждая команда выполняет одно действие: выводит список моделей, доступных вашему аккаунту, сообщает, сколько будет стоить генерация, запускает генерацию изображения или видео, дожидается её завершения и даёт ссылку для скачивания результата.

Писать код не нужно. Вы вводите команду, нажимаете Enter и читаете ответ.

CLI подойдёт, если вы хотите:

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

CLI работает с генерацией изображений и видео. Текстовые и чат-модели вызываются через эндпоинты, совместимые с форматом чата, — они описаны на странице Текст и потоковые ответы.

Есть ещё три официальных инструмента. Выбирайте CLI, если хотите вводить команды сами:

Пишете на другом языке? Официальные SDK есть и для Python, Go, PHP и Java.

Что можно делать

В командах выше слово в угловых скобках, например <task-id>, означает «подставьте сюда своё значение» — без самих скобок.

Перед началом

Вам понадобятся четыре вещи: терминал, Node.js, API-ключ и способ запускать CLI. В первый раз на это уходит около десяти минут.

node -v

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

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

npx @spicyapi/cli status

Ваш первый результат

В этом пошаговом примере вы сгенерируете одно изображение и скачаете его. На каждом шаге показаны команда, примерно то, что вы увидите, и что только что произошло. Ваши числа, ID и время будут другими.

spicyapi status

SpicyAPI is reachable — api.spicyapi.ai answered in 523 ms.

spicyapi balance

available: 12.34
held: 0.06
total: 12.40

spicyapi models list --modality image --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example image model",
      "modality": "image",
      "tasks": ["text-to-image"],
      "enabled": true,
      "available": true,
      "pricing": [
        { "variant": "", "unit": "per_image", "price": "0.03", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

{
  "model": "MODEL_ID_FROM_CATALOG",
  "enabled": true,
  "available": true,
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" },
      "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "9:16"] }
    },
    "additionalProperties": false
  }
}

cat > input.json <<'EOF'
{"prompt": "A paper lantern glowing on a rainy street at night, cinematic light"}
EOF

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: 0.03
maxCharge: 0.03
currency: USD
quantity: 1
unit: per_image
expiresAt: 2026-09-17T08:05:00Z

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z. Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241. Continue? [y/N]

Accepted: job_01k3m8x9q2z4v7n5p6r8s0t1w3
If waiting is interrupted: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
accepted: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","state":"queued","estimatedCost":"0.03","deadlineAt":"2026-09-17T08:30:00Z"}
task: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","model":"MODEL_ID_FROM_CATALOG","state":"succeeded","output":{"assets":[{"key":"tasks/…/result.png","url":"https://…","expiresAt":"2026-09-17T08:20:00Z","mime":"image/png","width":1024,"height":1024}]},"cost":"0.03","settled":true,…}

curl -L -o result.png "PASTE_THE_URL_HERE"

Как читать вывод

• Обычный вывод — по одной паре name: value на строку. Значения из нескольких частей, например output или retention, выводятся как JSON в одну строку.
• --json выводит полный ответ в виде JSON с отступами. Флаг работает с любой командой, до или после её имени: spicyapi --json balance и spicyapi balance --json — одно и то же.
• Результаты идут в обычный вывод, а сообщения — в поток ошибок. Цены, ключ идемпотентности, строки Accepted: и ошибки — это сообщения. Поэтому spicyapi --json tasks get <task-id> > task.json сохранит в task.json только результат, а сообщения по-прежнему появятся на экране.
• Ошибки выглядят как Error: <what went wrong> (request req_…), и обычно за ними следует строка Next: с подсказкой, что делать. С --json ошибка — это однострочный объект JSON с полями error, type, status, code и requestId, без строки Next:. Если ключ не задан, type равен MissingApiKeyError. Если обращаетесь в поддержку, укажите значение req_….
• Деньги — сумма в долларах США, записанная обычным текстом без знака $, например 0.03.
• Время указано в UTC. Z в конце 2026-09-17T08:05:00Z означает UTC.
• Код завершения равен 0, если команда выполнена успешно, и не равен 0, если она завершилась ошибкой; скрипты могут это проверять.

Справочник команд

У каждой команды есть встроенная справка: добавьте --help, например spicyapi tasks create --help.

Глобальные параметры и переменные окружения

Эти параметры работают с любой командой.

status

Что делает: проверяет, работает ли SpicyAPI и доступен ли он с вашего компьютера.

spicyapi status

Параметров нет. Ключ не нужен. Бесплатно.

Вывод: одно предложение. SpicyAPI is reachable — … answered in … ms. означает, что всё в порядке. could not be reached означает, что ваш компьютер не получил ответа: проверьте сеть или прокси. is not healthy или reports it is not ready означает проблему на нашей стороне; текущие инциденты публикуются на status.spicyapi.ai.

С --json вы увидите исходные результаты проверок. Главное — operational: true; запись readiness со статусом 404 на публичном адресе — это нормально.

docs search

Что делает: находит страницу документации по теме. Поиск идёт по небольшому индексу, встроенному в CLI, поэтому работает без ключа и без обращения к SpicyAPI. Каждый результат ведёт на страницу этого сайта документации, docs.spicyapi.ai.

spicyapi docs search [words] [--limit <count>]

spicyapi docs search retention

slug: retention
title: Retention and destruction
summary: What the platform caps are, how far down you can dial them, how to destroy a task's content, and what we cannot promise.
keywords: ["privacy","delete","storage","retention","per-request retention","purge","destroy"]
url: https://docs.spicyapi.ai/docs/retention

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

No documentation matched "refnd". Try fewer or different words, or run `spicyapi docs search` without words to browse pages.

С --json при отсутствии совпадений выводится пустой список, []. Бесплатно.

models list

Что делает: выводит модели, которые ваш аккаунт может вызывать сегодня, с ценами для вашего аккаунта.

spicyapi models list [options]

spicyapi models list --modality video --task image-to-video --json

Вывод: total и items. Используйте --json, потому что без него все элементы выводятся в одну строку. Самые полезные поля каждого элемента:

Бесплатно. Запросы списка моделей учитываются в лимите запросов вашего аккаунта, поэтому выполнять команду перед каждой генерацией не нужно.

models get

Что делает: показывает одну модель полностью, включая настройки, которые она принимает.

spicyapi models get <model>

spicyapi models get MODEL_ID_FROM_CATALOG --json

Вывод: те же поля, что у models list, плюс inputSchema. В inputSchema смотрите required (настройки, которые нужно отправить обязательно), properties (все допустимые настройки и их типы), enum (единственные допустимые значения), minimum и maximum (границы чисел) и default (значение, которое используется, если настройку не указать). Записи с именем x-ui — подсказки для построения форм, их можно не читать. Бесплатно.

balance

Что делает: показывает, сколько денег доступно на вашем аккаунте.

spicyapi balance

Параметров нет. Бесплатно.

Вывод: available (сколько можно потратить сейчас), held (зарезервировано под задачи, которые ещё выполняются) и total — всё в долларах США. Может быть и поле funding, которое разбивает баланс на предоплаченные средства и промоначисления, в том числе с указанием, когда истекают промоначисления и за какие модели ими можно платить. Проверять баланс перед каждой генерацией не нужно: tasks create делает это за вас.

usage

Что делает: показывает, сколько генераций выполнил текущий API-ключ и сколько они стоили, с группировкой по дням и по моделям.

spicyapi usage [--from <date>] [--to <date>]

spicyapi usage --from 2026-09-01 --to 2026-10-01

Эта команда охватывает весь сентябрь: --to — первый день, который не входит в выборку. Чтобы увидеть последние семь дней, включая сегодняшний, не указывайте ни один из параметров.

Вывод: from, to, currency, totalCalls, totalSpend, затем days (по дням: calls, succeeded, failed, spend) и models (те же числа по моделям). totalSpend учитывает только окончательные списания. days и models описывают одни и те же задачи двумя способами, поэтому не складывайте их. Чтобы увидеть данные по всему аккаунту, а не по одному ключу, откройте в консоли страницу Использование.

Бесплатно. Лимит — 30 вызовов в минуту, поэтому пользуйтесь командой для проверки итогов, а не в цикле.

tasks quote

Что делает: сообщает точную стоимость одной генерации, не запуская её и ничего не резервируя.

spicyapi tasks quote --model <model> --input-file <path>

Вывод: quoteId, model, estimatedCost, maxCharge, currency, quantity (например, число оплачиваемых секунд), unit и expiresAt. Расчёт стоимости действует пять минут.

Бесплатно, без подтверждения. Используйте эту команду, чтобы сравнивать модели или настройки. Перед tasks create запускать её не обязательно: та получает собственный расчёт стоимости.

tasks create

Что делает: запускает генерацию изображения или видео. Это стоит денег. CLI всегда сначала показывает цену и спрашивает.

spicyapi tasks create --model <model> --input-file <path> [options]

Что происходит по порядку:

1. CLI читает ваши входные данные и проверяет, что это объект JSON. Если входные данные не указаны, на этом всё останавливается.
2. Если ответить на вопрос некому, например в скрипте, а --yes не передан, на этом всё останавливается.
3. CLI получает расчёт стоимости и выводит ориентировочную стоимость, максимальную сумму списания, срок действия расчёта и ключ идемпотентности.
4. CLI спрашивает Continue? [y/N]. Продолжить можно только ответом y или yes. По умолчанию ответ — нет.
5. CLI создаёт задачу по рассчитанной цене. Ориентировочная стоимость резервируется на вашем балансе, и это же максимум, который может стоить задача.
6. Без --wait CLI выводит idempotencyKey, taskId, state (queued), estimatedCost и deadlineAt и возвращается. С --wait он сразу выводит Accepted: <task-id> и команду для восстановления, ждёт, а затем выводит idempotencyKey, accepted и завершённую задачу в task.

deadlineAt — самое позднее время, к которому задача может завершиться, прежде чем закончится с состоянием expired. Это не срок действия ссылки для скачивания и не срок хранения файлов.

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

В macOS и Linux входные данные можно передать и прямо в команде:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-json '{"prompt": "A paper lantern on a rainy street"}'

Если ожидание завершилось ошибкой (а не Ctrl + C), последние строки повторяют всё нужное, так что прокручивать вывод назад к строке Accepted: не придётся:

Error: task job_01k3m8x9q2z4v7n5p6r8s0t1w3 did not reach a terminal state within 600000ms
Task job_01k3m8x9q2z4v7n5p6r8s0t1w3 was accepted and may still be running; only the wait stopped.
Recover: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3
To replay the same request without creating a second task, reuse --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241.

Если у ошибки есть известное решение, например при 429 или ошибке сервера, дальше следует строка Next:. С --json те же сведения содержатся в объекте ошибки, в полях taskId, idempotencyKey и recover.

tasks wait

Что делает: ждёт, пока завершится задача, которую вы уже запустили.

spicyapi tasks wait <task-id> [options]

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000

Вывод: завершённая задача с теми же полями, что у tasks get, когда её состояние становится succeeded, failed или expired. Если задача выполнена успешно, но её файлы ещё копируются, команда подождёт ещё немного.

Если время ожидания истекло, вы увидите Error: task … did not reach a terminal state within 600000ms. Это не ошибка задачи: она всё ещё выполняется. Подождите снова, при необходимости с большим значением --wait-timeout-ms. Остановка ожидания никогда не отменяет задачу. Бесплатно.

tasks get

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

spicyapi tasks get <task-id>

Используйте тот же API-ключ, которым создана задача: с другим ключом вернётся «not found».

Поля вывода:

Обычный вывод заканчивается пояснением простыми словами, например Outputs expire: … или Content: Destroyed — you removed the outputs …. Каждый вызов возвращает свежие ссылки для скачивания. Бесплатно.

tasks list

Что делает: выводит задачи, созданные текущим API-ключом, по одной странице за раз.

spicyapi tasks list [options]

spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --state failed

Вывод: items (у каждого элемента taskId, model, state, cost, settled, createdAt, deadlineAt и completedAt), hasMore и nextCursor. Если hasMore равно true, выполните ту же команду ещё раз с теми же --from и --to, добавив --cursor со значением nextCursor. Ссылок для скачивания в списке нет; для нужной задачи используйте tasks get. Бесплатно.

tasks retry

Что делает: запускает задачу в состоянии failed или expired ещё раз — как новую задачу с новым ID. Это стоит денег.

spicyapi tasks retry <task-id> [options]

Команда спрашивает Retry source task … Continue? [y/N]. В отличие от tasks create, она не показывает цену перед вопросом. Новая задача оплачивается по текущей цене модели, поэтому, если цена важна, сначала проверьте её командой spicyapi models get <model>.

Вывод: idempotencyKey, новый taskId, sourceTaskId (исходная задача), state, estimatedCost (зарезервированная сумма) и deadlineAt.

• Повторить можно только задачи failed и expired, а также старые canceled. Чтобы получить другой вариант успешного результата, используйте tasks create.
• Исходные входные данные используются без изменений, поэтому повтор помогает, только если сбой был временным. Сначала проверьте errorCode; см. Повтор задачи, завершившейся ошибкой и Ошибки и повторы.
• Если входные данные ссылались на загруженный файл, срок действия которого уже истёк, повтор завершится ошибкой; загрузите файл заново и используйте tasks create.
• Повтор сохраняет настройку хранения исходной задачи.
• Если tasks create потерял соединение до того, как вы увидели ID задачи, это не задача, завершившаяся ошибкой. Вместо повтора действуйте по разделу Как вернуться к задаче после прерванного ожидания.

tasks purge

Что делает: безвозвратно удаляет у завершённой задачи сгенерированные медиа, данные результата (сохранённые данные о результате), промпт и прочий текст входных данных — сразу, не дожидаясь истечения срока хранения.

spicyapi tasks purge <task-id> [--yes]

Содержимое задачи в состоянии queued или running уничтожить нельзя. Отменить такую задачу тоже нельзя — ни команды, ни API для отмены нет, — поэтому дождитесь её завершения командой spicyapi tasks wait <task-id>, а затем уничтожьте содержимое.

Команда объясняет, что будет удалено, и просит подтверждения, потому что это действие нельзя отменить. Сначала скачайте всё, что хотите сохранить.

Вывод: taskId, contentState (purged), purgedAt, contentRemovedBy (user), billingRetained (всегда true) и mediaDeletionPending, а за ними строка, где перечислено уничтоженное и сказано, что сохранённые медиа будут удалены примерно в течение минуты. Если contentState по-прежнему present, на этот раз ничего не удалено; попробуйте позже.

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

files upload

Что делает: загружает файл с вашего компьютера, например исходное изображение для генерации видео из изображения, и выдаёт адрес spicy://, который нужно указать во входных данных.

spicyapi files upload <path> [--content-type <type>]

Поддерживаются изображения .jpg, .jpeg, .png, .webp и .gif до 10 MiB, видео .mp4 и .webm, а также аудио .mp3 и .wav до 90 MiB и не длиннее 600 секунд. Модель может задать собственные, более низкие ограничения.

spicyapi files upload ./start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z
width: 1280
height: 720

Вывод: скопируйте значение uri в точности так, как оно выведено, в настройку модели для файла — часто это image_url. Пользоваться адресом можно до expiresAt, обычно один день. После этого загрузите файл снова. Загрузка бесплатна.

files download-url

Что делает: создаёт новую ссылку для скачивания результата завершённой задачи. Команда выводит ссылку, но сам файл не сохраняет.

spicyapi files download-url <task-id> [--key <key>]

Вывод: key, url и expiresAt. Ссылка действует около 20 минут; откройте её в браузере или скачайте файл через curl. Для задачи, которая ещё не выполнена успешно, вернётся «not found». Если файл ещё копируется, вы получите ошибку конфликта; подождите несколько секунд и попробуйте снова. Когда файлы задачи удалены, новую ссылку создать нельзя. Бесплатно.

webhooks verify

Что делает: если у вас есть сервер, который принимает обратные вызовы SpicyAPI (см. --callback-url), команда проверяет, что сохранённый обратный вызов настоящий и не изменён. Она целиком работает на вашем компьютере, и API-ключ ей не нужен.

spicyapi webhooks verify --body-file <path> --timestamp <seconds> --signature <base64> --payload-version <version>

Вывод: при успехе — payload (содержимое обратного вызова), payloadVersion, taskId, deliveryId (в версии 2) и timestamp. Если что-то не совпадает, команда выводит ошибку и завершается с ненулевым кодом. Бесплатно.

Ключ подписи создаётся автоматически при регистрации, но его значение никогда не показывается. Чтобы получить ключ, который можно скопировать, откройте в консоли страницу Вебхуки и нажмите Создать (или Сменить, если ключ уже настроен). Новый ключ показывается только один раз. Смена ключа действует сразу и без переходного периода: старый ключ немедленно перестаёт подписывать. См. Webhook.

Готовые рецепты

Сгенерировать изображение

spicyapi models list --modality image --json
spicyapi models get MODEL_ID_FROM_CATALOG --json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Выберите ID в выводе первой команды, составьте input.json по настройкам, которые показывает вторая, затем запустите третью и подтвердите ответом y. Каждый шаг подробно разобран в разделе Ваш первый результат.

Превратить изображение в видео

spicyapi models list --modality video --task image-to-video --json
spicyapi models get MODEL_ID_FROM_CATALOG --json

spicyapi files upload ./start-frame.jpg

{
  "prompt": "Slow push-in, rain running down the window",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5
}

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait --wait-timeout-ms 1800000

Загруженным изображением можно пользоваться один день. После этого загрузите его снова.

Как вернуться к задаче после прерванного ожидания

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

• Вы видели Accepted: job_… или строку Recover: под ошибкой. У вас есть ID задачи. Подождите снова или просто посмотрите на неё:

  spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000
  spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

• Вы видели только строку Idempotency-Key: — например, потому что соединение оборвалось во время создания задачи. Выполните ту же команду ещё раз, с той же моделью и теми же входными данными, и добавьте этот ключ:

  spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241 --wait

  CLI снова покажет цену и спросит подтверждение, но если первая попытка была принята, SpicyAPI вернёт ту же самую задачу, а не запустит и не оплатит вторую. Это работает в течение 24 часов с тем же API-ключом. Если первая попытка так и не дошла, задача будет создана сейчас — один раз.

• У вас нет ни того, ни другого. Выведите список последних задач и найдите нужную по времени и модели:

  spicyapi --json tasks list --limit 10

Повтор задачи, завершившейся ошибкой

Сначала выясните, почему задача завершилась ошибкой:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Затем посмотрите errorCode. При ошибке или истечении срока задачи резерв обычно освобождается полностью. Некоторые отказы по содержанию оплачиваются по принятой цене, только если это исключение прямо указано на странице модели. Окончательную сумму проверяйте по settled и cost. tasks retry отправляет те же входные данные ещё раз, поэтому помогает, только если причина была временной:

Полный список — на странице Ошибки и повторы.

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

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait

Выгрузка расходов

Сохраните в файл расходы текущего ключа за месяц:

spicyapi --json usage --from 2026-09-01 --to 2026-10-01 > usage-2026-09.json

В файле — итоги по дням и по моделям. Чтобы получить список по отдельным задачам, сохраните так же вывод spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --limit 100, переходя по nextCursor, пока hasMore равно true. Данные по всему аккаунту и счета есть в консоли.

Запуск CLI из скрипта

В скрипте некому ответить на Continue? [y/N], поэтому платные команды отказываются выполняться, если не добавить --yes. Если добавляете:

• сначала получите расчёт стоимости и проверьте цену в самом скрипте;
• давайте каждой генерации собственный постоянный --idempotency-key, например poster-2026-09-17-v1, чтобы повторный запуск скрипта не привёл к двойному списанию;
• добавьте --json и читайте state из результата: код завершения 0 ещё не означает, что задача выполнена успешно;
• задайте для ключа лимиты расходов в консоли.

spicyapi --json tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key poster-2026-09-17-v1 --yes --wait > result.json

Стоимость, подтверждение и безопасность

Какие команды стоят денег. Только tasks create и tasks retry. Цены указаны в долларах США. Расчёт стоимости, просмотр списков, проверки, загрузка, скачивание и удаление бесплатны.

Цена заранее. tasks quote рассчитывает стоимость запроса, ничего не запуская. tasks create получает собственный расчёт и перед вопросом показывает Estimated charge и maximum charge. Когда задача принята, ориентировочная стоимость резервируется (held), и это же максимум, который с вас могут списать. Если задача выполнена успешно, вы платите за то, что фактически получено, но не больше этой суммы, а остаток возвращается на баланс.

Подтверждение. Continue? [y/N] означает, что ответ — нет, пока вы не введёте y. --yes отвечает за вас, поэтому используйте его, только когда уже знаете цену. Если CLI запущен там, где спросить нельзя, например в скрипте или с входными данными из конвейера, а --yes не указан, он отказывается выполнять команду, а не считает ответ положительным. tasks purge спрашивает так же, потому что удаление нельзя отменить. tasks retry тоже спрашивает, но цену заранее не показывает.

Ключ идемпотентности простыми словами. Это метка для одной генерации, вроде номера заказа. Каждая команда tasks create и tasks retry выводит такую метку. Если интернет пропал и вы не уверены, запустилась ли генерация, выполните ту же команду ещё раз с --idempotency-key и выведенным значением: вы получите исходную задачу, и деньги не будут списаны дважды. Метка действует 24 часа с тем же API-ключом. Не используйте её для другой генерации: тот же ключ с другими входными данными отклоняется.

Отмены нет. Принятую задачу отменить нельзя. Ctrl + C, закрытие терминала или отзыв ключа останавливают только ожидание; задача завершится и будет оплачена как обычно.

При ошибке или истечении срока задачи резерв обычно освобождается полностью. Некоторые отказы по содержанию оплачиваются по принятой цене, только если это исключение прямо указано на странице модели. Окончательную сумму проверяйте по settled и cost.

Скачивайте то, что хотите сохранить. Файлы результатов хранятся не дольше примерно 14 дней (или меньше, если так задано в аккаунте или в --retention), а затем удаляются навсегда. Ссылки для скачивания действуют около 20 минут, но пока файл существует, всегда можно запросить новую. Загруженными файлами можно пользоваться один день. Текст промптов по умолчанию стирается через 30 дней. Записи биллинга сохраняются. См. Хранение и удаление данных.

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

Ваш ключ. CLI читает ключ только из SPICY_API_KEY, никогда его не выводит, а в подсказках к ошибкам показывает не больше первых девяти символов (sk-spicy-).

Подробнее: Оплата, Идемпотентность, Необратимость и повтор.

Устранение неполадок

Найдите сообщение, которое видите. Ошибки от SpicyAPI заканчиваются на (request req_…); если обращаетесь в поддержку, укажите это значение, но никогда не отправляйте свой ключ.

Все коды ошибок объяснены на странице Ошибки и повторы, а шаги восстановления — на странице Диагностика и восстановление.

Исходный код

Пакет распространяется под лицензией MIT и разрабатывается открыто по адресу github.com/spicyapi-ai/spicy-cli. Там же можно прочитать код любой команды с этой страницы, сообщить о поведении, которое расходится с описанным, или предложить изменение.

Что дальше