Herramienta de línea de comandos (CLI)

Qué es la CLI

spicyapi es un pequeño programa que se ejecuta en una terminal, la ventana en la que escribes comandos en lugar de hacer clic en botones. Cada comando hace una sola cosa: listar los modelos que puede usar tu cuenta, decirte cuánto costará una generación, iniciar una generación de imagen o de video, esperar a que termine y darte un enlace para descargar el resultado.

No escribes ni una línea de código. Escribes un comando, pulsas Enter y lees la respuesta.

Te viene bien si quieres:

• probar modelos y comparar precios antes de que nadie escriba una integración;
• generar imágenes o videos desde tu propio equipo y guardar los archivos;
• repetir el mismo tipo de generación sin tener que pasar cada vez por una página;
• revisar los ajustes exactos de un modelo antes de construir algo sobre él.

La CLI se ocupa de la generación de imágenes y videos. Los modelos de texto y de chat se llaman a través de los endpoints compatibles con chat que se describen en Texto y streaming.

Hay otras tres herramientas oficiales. Elige la CLI si quieres escribir los comandos tú mismo:

¿Escribes en otro lenguaje? También hay SDK oficiales para Python, Go, PHP y Java.

Qué puedes hacer

En los comandos de arriba, una palabra entre ángulos como <task-id> significa «pon aquí tu propio valor», sin los ángulos.

Antes de empezar

Necesitas cuatro cosas: una terminal, Node.js, una clave de API y una forma de ejecutar la CLI. La primera vez lleva unos diez minutos.

node -v

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

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

npx @spicyapi/cli status

Tu primer resultado

Este recorrido genera una imagen y la descarga. Cada paso muestra el comando, más o menos lo que vas a ver y lo que acaba de pasar. Tus números, IDs y horas serán distintos.

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"

Cómo leer la salida

• La salida normal muestra un name: value por línea. Los valores que tienen varias partes, como output o retention, se muestran como JSON en una sola línea.
• --json muestra la respuesta completa como JSON sangrado. Funciona con todos los comandos, antes o después del nombre del comando: spicyapi --json balance y spicyapi balance --json son lo mismo.
• Los resultados van a la salida normal de la pantalla y los mensajes, a la salida de errores. Los precios, la clave de idempotencia, las líneas Accepted: y los errores son mensajes. Por eso spicyapi --json tasks get <task-id> > task.json guarda en task.json solo el resultado, mientras que los mensajes siguen apareciendo en pantalla.
• Los errores tienen la forma Error: <what went wrong> (request req_…), normalmente seguida de una línea Next: que dice qué hacer. Con --json, un error es un objeto JSON de una sola línea con error, type, status, code y requestId, sin línea Next:. Cuando no hay clave configurada, type es MissingApiKeyError. Si contactas con soporte, indica el valor req_….
• El dinero es un importe en dólares estadounidenses escrito como texto normal, sin el signo $, por ejemplo 0.03.
• Las horas están en UTC. La Z del final de 2026-09-17T08:05:00Z significa UTC.
• El código de salida es 0 cuando un comando sale bien y distinto de 0 cuando falla, algo que los scripts pueden comprobar.

Referencia de comandos

Todos los comandos traen su propia ayuda: añade --help, por ejemplo spicyapi tasks create --help.

Opciones globales y variables de entorno

Estas opciones funcionan con todos los comandos.

status

Qué hace: comprueba si SpicyAPI está en marcha y si se puede llegar a él desde tu equipo.

spicyapi status

Sin opciones. No necesita clave. Gratuito.

Salida: una frase. SpicyAPI is reachable — … answered in … ms. significa que todo va bien. could not be reached significa que tu equipo no recibió respuesta: revisa tu red o tu proxy. is not healthy o reports it is not ready indican un problema por nuestra parte; las incidencias en curso aparecen en status.spicyapi.ai.

Con --json ves las comprobaciones en bruto. La respuesta que importa es operational: true; una entrada readiness con estado 404 es normal en la dirección pública.

docs search

Qué hace: encuentra la página de documentación sobre un tema. Busca en un pequeño índice incluido en la CLI, así que funciona sin clave y sin llamar a SpicyAPI. Cada resultado enlaza a la página de este sitio de documentación, 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

Cuando hay varios resultados, se muestran uno detrás de otro y cada uno empieza por slug:. Si no hay coincidencias, lo indica y aun así termina con código de salida 0:

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

Con --json, cuando no hay coincidencias se muestra una lista vacía, []. Gratuito.

models list

Qué hace: lista los modelos que tu cuenta puede llamar hoy, con los precios que paga tu cuenta.

spicyapi models list [options]

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

Salida: total e items. Usa --json, porque sin esa opción todos los elementos se muestran en una sola línea. Los campos más útiles de cada elemento:

Gratuito. La lista de modelos cuenta para el límite de solicitudes de tu cuenta, así que no hace falta ejecutarla antes de cada generación.

models get

Qué hace: muestra un modelo completo, incluidos los ajustes que acepta.

spicyapi models get <model>

spicyapi models get MODEL_ID_FROM_CATALOG --json

Salida: los mismos campos que models list, más inputSchema. En inputSchema, lee required (los ajustes que tienes que enviar), properties (todos los ajustes permitidos y su tipo), enum (los únicos valores permitidos), minimum y maximum (límites numéricos) y default (el valor que se usa si omites el ajuste). Las entradas llamadas x-ui son pistas para construir formularios; puedes ignorarlas. Gratuito.

balance

Qué hace: muestra cuánto dinero hay disponible en tu cuenta.

spicyapi balance

Sin opciones. Gratuito.

Salida: available (lo que puedes gastar ahora), held (lo retenido para tareas que todavía están en marcha) y total, todo en dólares estadounidenses. También puede incluir funding, que divide el saldo en fondos prepagados y bonos promocionales, con la fecha en que caducan los bonos y los modelos que pagan. No hace falta consultar el saldo antes de cada generación: tasks create lo comprueba por ti.

usage

Qué hace: muestra cuántas generaciones ejecutó la clave de API actual y cuánto costaron, agrupadas por día y por modelo.

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

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

Esto abarca todo septiembre: --to es el primer día que no se incluye. Omite las dos opciones para ver los últimos siete días, hoy incluido.

Salida: from, to, currency, totalCalls, totalSpend, y después days (por día: calls, succeeded, failed, spend) y models (las mismas cifras por modelo). totalSpend solo cuenta los cargos definitivos. days y models describen las mismas tareas de dos maneras, así que no los sumes. Para ver toda tu cuenta y no solo una clave, usa la página Consumo de la consola.

Gratuito. Está limitado a 30 llamadas por minuto, así que úsalo para consultar totales, no dentro de un bucle.

tasks quote

Qué hace: te dice exactamente cuánto costaría una generación, sin iniciarla y sin retener dinero.

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

Salida: quoteId, model, estimatedCost, maxCharge, currency, quantity (por ejemplo, el número de segundos que se cobran), unit y expiresAt. Una cotización es válida durante cinco minutos.

Gratuito y sin confirmación. Úsalo para comparar modelos o ajustes. No tienes por qué ejecutarlo antes de tasks create, que obtiene su propia cotización.

tasks create

Qué hace: inicia una generación de imagen o de video. Esto cuesta dinero. La CLI siempre muestra el precio y pregunta antes.

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

Qué pasa, por orden:

1. La CLI lee tu entrada y comprueba que es un objeto JSON. Si no has dado ninguna entrada, se detiene aquí.
2. Si nadie puede responder a una pregunta, por ejemplo en un script, y no has pasado --yes, se detiene aquí.
3. Obtiene una cotización y muestra el cargo estimado, el cargo máximo, cuándo caduca la cotización y la clave de idempotencia.
4. Pregunta Continue? [y/N]. Solo y o yes continúan. La respuesta predeterminada es no.
5. Crea la tarea al precio cotizado. El importe estimado se retiene de tu saldo, y ese importe es también lo máximo que puede costar la tarea.
6. Sin --wait, muestra idempotencyKey, taskId, state (queued), estimatedCost y deadlineAt, y vuelve. Con --wait, muestra enseguida Accepted: <task-id> y un comando de recuperación, espera y después muestra idempotencyKey, accepted y la task terminada.

deadlineAt es la hora límite en la que la tarea puede terminar antes de acabar como expired. No es la hora a la que caducan tu enlace de descarga o tus archivos.

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

En macOS y Linux también puedes dar la entrada en la misma línea:

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

Cuando la espera falla con un error (y no por Ctrl + C), las últimas líneas repiten todo lo que necesitas, para que no tengas que volver atrás a buscar la línea 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.

Si el error tenía una solución conocida, como un 429 o un error del servidor, a continuación aparece una línea Next:. Con --json, los mismos datos están en el objeto de error como taskId, idempotencyKey y recover.

tasks wait

Qué hace: espera a que termine una tarea que ya iniciaste.

spicyapi tasks wait <task-id> [options]

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

Salida: la tarea terminada, con los mismos campos que tasks get, en cuanto su estado es succeeded, failed o expired. Si la tarea salió bien pero sus archivos todavía se están copiando, sigue esperando un poco más.

Si se agota el límite de tiempo, ves Error: task … did not reach a terminal state within 600000ms. Eso no es un fallo: la tarea sigue en marcha. Vuelve a esperar, con un --wait-timeout-ms más largo si hace falta. Dejar de esperar nunca cancela una tarea. Gratuito.

tasks get

Qué hace: muestra una tarea tal como está ahora: su estado, su costo, los enlaces al resultado y cuándo se borrará su contenido.

spicyapi tasks get <task-id>

Usa la misma clave de API con la que se creó la tarea: con otra clave recibirás «not found».

Campos de la salida:

La salida normal termina con un resumen en lenguaje llano, como Outputs expire: … o Content: Destroyed — you removed the outputs …. Cada llamada devuelve enlaces de descarga nuevos. Gratuito.

tasks list

Qué hace: lista las tareas creadas con la clave de API actual, página a página.

spicyapi tasks list [options]

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

Salida: items (cada uno con taskId, model, state, cost, settled, createdAt, deadlineAt y completedAt), hasMore y nextCursor. Si hasMore vale true, vuelve a ejecutar el mismo comando con los mismos --from y --to, añadiendo --cursor con el valor de nextCursor. La lista no incluye enlaces de descarga; usa tasks get con la tarea que te interese. Gratuito.

tasks retry

Qué hace: vuelve a ejecutar una tarea failed o expired como una tarea nueva, con un ID nuevo. Esto cuesta dinero.

spicyapi tasks retry <task-id> [options]

Pregunta Retry source task … Continue? [y/N]. A diferencia de tasks create, no muestra ningún precio antes de preguntar. La tarea nueva se cobra al precio actual del modelo, así que, si el precio te importa, consúltalo antes con spicyapi models get <model>.

Salida: idempotencyKey, el nuevo taskId, sourceTaskId (la original), state, estimatedCost (el importe retenido) y deadlineAt.

• Solo se pueden reintentar las tareas failed y expired, además de las antiguas canceled. Si quieres otra versión de un resultado que salió bien, usa tasks create.
• La entrada original se reutiliza sin cambios, así que un reintento solo sirve cuando el fallo fue pasajero. Mira primero errorCode; consulta Reintentar una tarea que falló y Errores.
• Si la entrada apuntaba a un archivo subido que ya ha caducado, el reintento falla; vuelve a subir el archivo y usa tasks create.
• El reintento mantiene el ajuste de conservación de la tarea original.
• Si tasks create perdió la conexión antes de que vieras un ID de tarea, eso no es una tarea fallida. Sigue los pasos de Retomar una tarea después de que se interrumpiera la espera.

tasks purge

Qué hace: borra para siempre, en el acto y sin esperar a que caduquen, los medios generados, el resultado (los datos guardados del resultado), el prompt y el resto del texto de entrada de una tarea terminada.

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

Una tarea que sigue en queued o running no se puede purgar. Tampoco se puede cancelar —no existe ningún comando ni ninguna API de cancelación—, así que espera a que termine con spicyapi tasks wait <task-id> y después púrgala.

Explica qué se va a borrar y te pide que confirmes, porque no se puede deshacer. Descarga antes lo que quieras conservar.

Salida: taskId, contentState (purged), purgedAt, contentRemovedBy (user), billingRetained (siempre true) y mediaDeletionPending, seguidos de una línea que indica qué se destruyó y que los medios guardados se eliminan en aproximadamente un minuto. Si contentState sigue siendo present, esta vez no se eliminó nada; vuelve a intentarlo más tarde.

Gratuito, y no es un reembolso: el movimiento contable, el importe cobrado, el modelo, el estado, las marcas de tiempo y el ID de solicitud se quedan registrados. Consulta Conservación y destrucción.

files upload

Qué hace: sube un archivo de tu equipo, como la imagen inicial de una generación de imagen a video, y te da una dirección spicy:// para ponerla en tu entrada.

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

Se admiten imágenes .jpg, .jpeg, .png, .webp y .gif de hasta 10 MiB, videos .mp4 y .webm y audios .mp3 y .wav de hasta 90 MiB y 600 segundos. Cada modelo puede fijar sus propios límites, más bajos.

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

Salida: copia el valor de uri, exactamente como aparece, en el ajuste de archivo del modelo, que a menudo es image_url. Se puede usar hasta expiresAt, normalmente un día. Pasado ese plazo, vuelve a subir el archivo. Subir archivos es gratuito.

files download-url

Qué hace: crea un enlace de descarga nuevo para el resultado de una tarea terminada. Muestra el enlace; no guarda el archivo.

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

Salida: key, url y expiresAt. El enlace funciona durante unos 20 minutos; ábrelo en un navegador o descárgalo con curl. Una tarea que todavía no ha salido bien responde «not found». Si el archivo todavía se está copiando, recibes un error de conflicto; espera unos segundos y vuelve a intentarlo. Cuando los archivos de la tarea ya se han borrado, no se puede crear ningún enlace nuevo. Gratuito.

webhooks verify

Qué hace: si tienes un servidor que recibe callbacks de SpicyAPI (consulta --callback-url), comprueba que un callback que guardaste es auténtico y no se ha modificado. Se ejecuta por completo en tu equipo y no necesita clave de API.

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

Salida: si todo cuadra, payload (el contenido del callback), payloadVersion, taskId, deliveryId (versión 2) y timestamp. Si algo no coincide, muestra un error y termina con un código de salida distinto de cero. Gratuito.

Al registrarte se crea automáticamente una clave de firma, pero su valor no se muestra nunca. Para obtener una que puedas copiar, abre Webhooks en la consola y haz clic en Generar (o en Rotar si ya hay una configurada). La clave nueva se muestra una sola vez. La rotación surte efecto al instante, sin periodo de transición: la clave antigua deja de firmar en ese mismo momento. Consulta Webhooks.

Recetas habituales

Generar una imagen

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

Elige un ID con el primer comando, prepara input.json con los ajustes que muestra el segundo y ejecuta el tercero, confirmando con y. El recorrido de Tu primer resultado explica cada paso.

Convertir una imagen en un video

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

La imagen subida se puede usar durante un día. Pasado ese plazo, vuelve a subirla.

Retomar una tarea después de que se interrumpiera la espera

Una tarea sigue en marcha aunque se cierre la terminal, se corte la red, tu equipo entre en reposo o se agote la espera. Cómo recuperarla depende de lo que llegaste a ver:

• Viste Accepted: job_…, o una línea Recover: debajo del error. Tienes el ID de tarea. Vuelve a esperar, o simplemente consúltala:

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

• Solo viste la línea Idempotency-Key:, por ejemplo porque la conexión se cortó mientras se creaba la tarea. Ejecuta otra vez el mismo comando, con el mismo modelo y la misma entrada, y añade esa clave:

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

  La CLI vuelve a mostrar el precio y a preguntar, pero, si el primer intento se aceptó, SpicyAPI te devuelve esa misma tarea en lugar de iniciar y cobrar una segunda. Funciona durante 24 horas con la misma clave de API. Si el primer intento nunca llegó, la tarea se crea ahora, una sola vez.

• No tienes ninguna de las dos cosas. Lista tus tareas recientes y búscala por hora y por modelo:

  spicyapi --json tasks list --limit 10

Reintentar una tarea que falló

Primero averigua por qué falló:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Después lee errorCode. Las tareas fallidas o vencidas normalmente liberan toda la retención. Algunos rechazos de contenido se cobran al precio aceptado, solo si la página del modelo indica expresamente esta excepción. Consulta settled y cost para conocer el importe final. tasks retry vuelve a enviar la misma entrada, así que solo sirve cuando la causa fue pasajera:

La lista completa está en Errores.

Cuando un reintento tenga sentido, ejecútalo. Crea, y cobra, una tarea nueva:

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait

Exportar tu consumo

Guarda en un archivo un mes de consumo de la clave actual:

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

El archivo contiene los totales por día y por modelo. Para una lista tarea por tarea, guarda del mismo modo spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --limit 100, siguiendo nextCursor mientras hasMore valga true. Las cifras de toda la cuenta y las facturas están en la consola.

Ejecutar la CLI desde un script

En un script nadie puede responder a Continue? [y/N], así que los comandos de pago se niegan a ejecutarse salvo que añadas --yes. Cuando lo hagas:

• cotiza primero y comprueba el precio dentro del script;
• da a cada generación su propia --idempotency-key fija, como poster-2026-09-17-v1, para que ejecutar el script dos veces no cobre dos veces;
• añade --json y lee state en el resultado: que un comando termine con código de salida 0 no significa necesariamente que haya producido una tarea que salió bien;
• fija límites de gasto para la clave en la consola.

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

Costos, confirmación y seguridad

Qué comandos cuestan dinero. Solo tasks create y tasks retry. Los precios están en dólares estadounidenses. Cotizar, listar, consultar, subir, descargar y borrar es gratuito.

Ver el precio primero. tasks quote calcula el precio de una solicitud sin iniciar nada. tasks create obtiene su propia cotización y muestra Estimated charge y maximum charge antes de preguntar. Cuando se acepta la tarea, el importe estimado queda retenido (held) y es también lo máximo que se te puede cobrar. Cuando la tarea sale bien, pagas por lo que realmente se produjo, nunca más de ese importe, y lo que sobre vuelve a tu saldo.

La confirmación. Continue? [y/N] significa que la respuesta es no salvo que escribas y. --yes responde por ti, así que úsalo solo cuando ya conozcas el precio. Si la CLI se ejecuta en un sitio donde no puede preguntar, como un script o con una entrada pasada por una tubería, y no hay --yes, se niega en lugar de dar por hecho que sí. tasks purge pregunta de la misma manera, porque un borrado no se puede deshacer. tasks retry también pregunta, pero sin mostrar antes un precio.

La clave de idempotencia, en pocas palabras. Es una etiqueta para una generación, como un número de pedido. Cada tasks create y cada tasks retry muestra una. Si se te corta internet y no sabes si la generación llegó a empezar, ejecuta otra vez el mismo comando con --idempotency-key y el valor que se mostró: recuperas la tarea original y no se te cobra dos veces. La etiqueta funciona durante 24 horas con la misma clave de API. No la reutilices para otra generación: la misma clave con una entrada distinta se rechaza.

No se puede cancelar. Una vez aceptada, una tarea no se puede cancelar. Ctrl + C, cerrar la terminal o revocar la clave solo detiene la espera; la tarea termina y se cobra con normalidad.

Las tareas fallidas o vencidas normalmente liberan toda la retención. Algunos rechazos de contenido se cobran al precio aceptado, solo si la página del modelo indica expresamente esta excepción. Consulta settled y cost para conocer el importe final.

Descarga lo que quieras conservar. Los archivos de resultado se guardan como máximo unos 14 días, o menos si así lo indican tu cuenta o --retention, y después se borran para siempre. Los enlaces de descarga duran unos 20 minutos, pero mientras el archivo exista siempre puedes pedir uno nuevo. Los archivos subidos se pueden usar durante un día. El texto del prompt se borra a los 30 días de forma predeterminada. Los registros de facturación se conservan. Consulta Conservación y destrucción.

Límites de gasto. Cada clave puede tener un límite diario, uno mensual y uno acumulado, que se fijan en la página Claves de API. Las claves nuevas no tienen límite hasta que fijas uno. Una tarea que superaría un límite se rechaza antes de empezar.

Tu clave. La CLI solo lee la clave de SPICY_API_KEY, nunca la muestra y, en las pistas de los errores, enseña como mucho sus nueve primeros caracteres (sk-spicy-).

Más detalles: Facturación, Idempotencia, Ejecución y reintentos.

Solución de problemas

Busca el mensaje que ves. Los errores de SpicyAPI terminan en (request req_…); incluye ese valor si contactas con soporte, pero no envíes nunca tu clave.

Todos los códigos de error se explican en Errores, y los pasos de recuperación están en Diagnóstico y recuperación.

Código fuente

El paquete tiene licencia MIT y se desarrolla en abierto en github.com/spicyapi-ai/spicy-cli. Ahí puedes leer el código detrás de cualquier comando de esta página, avisar de un comportamiento que no coincida con lo descrito o proponer un cambio.

Siguientes pasos