SpicyAPI Skill

---
name: spicyapi
description:
  Use the SpicyAPI public developer API through the official SDK, CLI, or MCP server to inspect live
  models, create, retry, and wait for media tasks, upload inputs, retrieve outputs, keep files in
  the personal or team asset library, set how long results are kept, destroy a task's stored
  content, check balances, and verify webhooks. Use for SpicyAPI integration and API operations; not
  for browser-account administration, payments, or publishing provider models.
metadata:
  short-description: Operate SpicyAPI through its SDK, CLI, or MCP server
---

# SpicyAPI

Use the packaged `spicyapi_*` MCP tools when they are connected. Otherwise use the `spicyapi` CLI
for operations or `SpicyClient` for application code. Treat the live model catalog and the bundled
OpenAPI contract as authoritative.

Read [references/api-workflows.md](references/api-workflows.md) before composing API, CLI, or MCP
operations. Read [references/safety.md](references/safety.md) before billable calls, real
integration tests, webhook handling, credential work, or cleanup.

## Required behavior

- Obtain the selected model's live input schema once: get a known model, or discover it in the
  catalog. Reuse a complete record already returned with `includeSchema`; refresh when it is missing
  or stale. Never invent a model ID, price, provider capability, or input field.
- Before a key exists, `GET https://api.spicyapi.ai/console/v1/catalog/models` answers "which models
  are there and what do they cost" with no credentials, so an evaluation is never blocked on signing
  up. It is a plain HTTPS GET with no SDK, CLI, or MCP wrapper. Switch to the authenticated catalog
  as soon as a key is available: only that one is scoped to the key, carries the full input schema
  and validated examples, and is the surface task creation's `model` is tied to. Never build `input`
  from the anonymous list.
- Pass the model-specific `input` object through unchanged. The SpicyAPI server owns schema, price,
  balance, operational API-key scope, and routing decisions.
- Choose model capabilities from the live catalog. No content-mode request flag or platform content
  review is required.
- Treat task creation and retry as billable. On a model whose page says refused requests are billed,
  a `content_rejected` task is charged its accepted estimate, so never resend a refused request
  unchanged there. CLI and MCP creation obtain and confirm the exact quote internally; do not call
  the separate quote command/tool first unless comparing prices. In SDK code, quote the exact
  request once, show its USD estimate and maximum charge, confirm it, and pass that quote into
  creation. Preserve one idempotency key for the entire logical attempt, including recovery from an
  uncertain response.
- Health/readiness and balance checks are optional diagnostics, not a per-task checklist. The server
  validates availability and funds when accepting a task.
- When the user points at a file on their own machine, upload it first and pass the returned
  `spicy://` URI in `input` (or in a chat message part): `spicyapi_upload_file` on MCP,
  `spicyapi files upload <path>` on the CLI, `client.uploadFile(path)` in the SDK. Public HTTPS
  media URLs need no upload. Never inline file bytes or base64 into task input, and never treat a