SpicyAPI MCP

Permanently delete one asset from the library this key reaches. Its spicy://a/<id> uri stops working in new requests at once and the stored file is removed; there is no undo. In a team library, developers can delete only what they saved. Deleting does not give back today's allowance of new assets. Only delete an asset the user named. Requires a user confirmation round.

Change an asset's name. Its spicy://a/<id> uri stays the same, so model inputs that already use it keep working.

Keep a file in the asset library this key reaches (personal, or the team's shared library for a team key) until it is deleted, and return its spicy://a/<id> uri for later model inputs made with keys of the same workspace. Give exactly one source: taskId (an output of one of the user's own successful tasks, or of the team's with a team key; index or key picks which, the first output by default), path (an absolute path to a file on this computer, uploaded first), url (a public http or https file), or fileId (a committed spicy://f/ upload). Saving the same task output, upload or URL again returns the existing asset. Storage unlocks with lifetime top-ups; a refusal carries a reason (asset_library_locked, asset_library_full, asset_file_too_large, asset_daily_limit, asset_storage_full) — call spicyapi_assets_usage_get to explain the plan rather than retrying.

List files in the asset library this key reaches — the personal library for a personal key, the team's shared library for a team key — newest first unless sort says otherwise, one page at a time; pass nextCursor back as cursor with the same filters and sort to continue (a cursor from another sort is rejected with 400). Narrow it with favorite, collectionId (a folder; folders are created on the web, and an id outside this library is a 404), entityId (the images of one character) and query. Each item's uri (spicy://a/<id>) goes straight into any media field of a model input — no upload or download step. previewUrl is a private preview signed for at most 20 minutes; use it to show the file, never store it. A change the key's team role does not allow gets 403 with reason asset_permission_denied; a key that cannot reach the library gets 403 with asset_workspace_forbidden.

Return which library the key reaches (scope), the storage plan, what is stored against its limits, how many assets were saved today against the daily limit, and the next plan with how much more to top up. Usage covers the owner's whole allowance, shared by their personal and team libraries; the top-up amounts are absent when scope.canTopUp is false. Plans unlock with lifetime top-ups and never go down; byte values use binary units (500 MB = 524288000 bytes). Use it to explain a refused save.

Return available, held, and total balance as exact decimal USD strings when requested or diagnosing funds. Task creation already checks funds; this is not a prerequisite.

Read one character with its images in order, each with its uri and a fresh private previewUrl (signed for at most 20 minutes; never store it). An unknown character and one outside this key's library both return 404. To use a character, put the uri (spicy://a/<id>) of its images, in the order given, into the reference image field of the model's input (spicyapi_model_get shows which field), and refer to them in the prompt the way that model's page describes. Characters are created and edited on the web; these tools only read them. Older spicy://p/<id> persona references still resolve to the same images, in the personal library only.

List the characters in the asset library this key reaches: named sets of images, each image an asset with its own uri. Newest first, one page at a time; pass nextCursor back as cursor to continue. Pass assetId to find the characters that contain one asset. To use a character, put the uri (spicy://a/<id>) of its images, in the order given, into the reference image field of the model's input (spicyapi_model_get shows which field), and refer to them in the prompt the way that model's page describes. Characters are created and edited on the web; these tools only read them. Older spicy://p/<id> persona references still resolve to the same images, in the personal library only.

Search the bundled index of verified first-party documentation URLs.

Create a short-lived signed URL for an output owned by the current task and API key, for legacy integrations or explicit link renewal. Prefer existing ready output.assets[].url from task_get, task_wait, or a verified v2 webhook; no ticket call is needed for those links.

Return one exact model, its live input schema, pricing, policy and availability. Reuse a complete record already obtained from models_list with includeSchema. The input schema is plain JSON Schema; display-only and rate-card annotations are removed. Some input values change the price; task_create obtains the exact request quote for confirmation. Use pricing entries for comparisons rather than calculating the accepted charge yourself.

Discover enabled models and account-specific prices. Fetch only the selected model for its schema, or set includeSchema to reuse complete records without another model_get call. Returned input schemas are plain JSON Schema; display-only and rate-card annotations are removed. Some input values change the price; task_create obtains the exact request quote for confirmation. Use pricing entries for comparisons rather than calculating the accepted charge yourself. Models with task `realtime` or `realtime-transcription` take one bounded turn as a task from their input schema; live, continuous audio needs a server-side WebSocket to wss://api.spicyapi.ai/v1/realtime, which this server does not open. Embedding models (task `embedding`) and text-to-speech models are also served by OpenAI-compatible POST /v1/embeddings and POST /v1/audio/speech for applications that want vectors or audio bytes directly.

Read public health and readiness endpoints for diagnostics or an explicit status request. Not a prerequisite for task creation. No API key is required. Report the `operational` field. On the public surface /readyz answers 404 by design — readiness exposes database and Redis state, so it is registered only on the admin process — and `operational` already accounts for that. Do not report a 404 there as an outage.

Obtain the exact request quote, show its USD estimate and maximum charge for user confirmation, then reserve funds and create an asynchronous task. Do not call task_quote first unless independently comparing prices. The confirmation needs an MCP client that supports form elicitation; if the client does not, the call fails after the free quote and no task is created or charged. Models with task `realtime` or `realtime-transcription` take one bounded turn as a task from their input schema; live, continuous audio needs a server-side WebSocket to wss://api.spicyapi.ai/v1/realtime, which this server does not open. Embedding models (task `embedding`) and text-to-speech models are also served by OpenAI-compatible POST /v1/embeddings and POST /v1/audio/speech for applications that want vectors or audio bytes directly.

Read a task created by the current API key, including ready output.assets[].url links. Use those URLs directly without your API key; query again if assets are pending or URLs have expired. A verified complete v2 webhook already contains the result. Unknown and inaccessible IDs are both 404. Some models answer in words instead of a file: speech-to-text and other text results arrive in output.text with no assets, and a transcription may add output.transcript with word timings, timed segments (output.transcript.segments, with speaker labels when available) and the detected language. Embedding models return vectors in output.embeddings (inputTokens and data[].index/embedding); large results are summarized here, see output.embeddings.summary. Layer decomposition returns one image asset per layer; stack them by ascending output.assets[].layer.zIndex. Other asset roles: image-to-3d and text-to-3d return one `mesh` asset (a binary glTF .glb, mime model/gltf-binary); vector endpoints return `image` assets with mime image/svg+xml; video translation can add a `subtitle` asset (.srt); video extension that joins the source clip returns the joined `video` first and the new part as `segment`.

Permanently destroy one terminal task's stored content: generated media, result payload, prompt, and input text. This destroys content, not the record of what it cost — the ledger entry, charged amount, model, state, timestamps and request ID all stay queryable afterwards, so this never hides or reverses a charge and never refunds anything. It cannot be undone and there is no per-output granularity: the unit is one whole task. Download any result the user still wants before calling this. Only tasks in a terminal state are accepted. An accepted task cannot be canceled and there is no cancellation API, so for a queued or running task wait until it finishes (task_wait), then purge it. Repeating the call on an already destroyed task succeeds and changes nothing. Requires a user confirmation round.

Compare an exact request price without creating a task or reserving funds. Returns a five-minute USD estimate and maximum charge. task_create already obtains its own quote and confirmation; do not call this tool as a routine prerequisite.

Create a new task from a failed or expired source. Requires a user confirmation round.

Wait for a task for up to 300 seconds and read ready output.assets[].url directly without a download-ticket call. By default, polling backs off from about 2 to at most 10 seconds; an explicit intervalSeconds stays fixed. Prefer signed webhooks for production; a complete verified v2 callback needs no extra task_get. A local wait timeout does not cancel the task. Some models answer in words instead of a file: speech-to-text and other text results arrive in output.text with no assets, and a transcription may add output.transcript with word timings, timed segments (output.transcript.segments, with speaker labels when available) and the detected language. Embedding models return vectors in output.embeddings (inputTokens and data[].index/embedding); large results are summarized here, see output.embeddings.summary. Layer decomposition returns one image asset per layer; stack them by ascending output.assets[].layer.zIndex. Other asset roles: image-to-3d and text-to-3d return one `mesh` asset (a binary glTF .glb, mime model/gltf-binary); vector endpoints return `image` assets with mime image/svg+xml; video translation can add a `subtitle` asset (.srt); video extension that joins the source clip returns the joined `video` first and the new part as `segment`.

Discover current-key task history with metadata only, without fetching each result. Dates are UTC [from,to), default seven days, at most 92 days. Keep from/to fixed across pages and pass nextCursor unchanged. Limit defaults to 20, maximum 100. Cost is an exact USD string and is final only when settled. Use task_get only for selected results; use usage_get for settled spending including hidden tasks. This is not a polling endpoint or a prerequisite to generation.

Read a file from this computer, upload it, and return the spicy:// URI to put in a model input field. Use this whenever the user refers to a file on their machine. Images (JPEG, PNG, WebP, GIF) up to 10 MiB; MP4/WebM video and MP3/WAV audio up to 90 MiB; reference documents (PDF, Word, Excel, PowerPoint, Keynote, Pages, Numbers, TXT, Markdown) up to 90 MiB for fields such as reference_file_url. Public HTTPS media URLs need no upload at all — pass them straight to the model input when its schema accepts a URL.

Read task counts and settled actual USD spend for the current API key, grouped by creation day and model. Only from/to dates are accepted: UTC [from,to), at most 92 days; defaults to seven days ending tomorrow UTC. Money is returned as exact decimal strings; pending holds are excluded and late settlement can change prior-day spend. This is not account balance or remaining key budget, and is not a generation prerequisite. Use for requested usage reports; respect Retry-After on rate limits.