AI agents

Connect an AI agent (MCP)

Spicy API runs a remote MCP server so a coding agent or assistant can quote prices, check the balance, hand the user a top-up link, generate images and video, and watch spend on the user's account. The human approves each spend in the chat. Endpoint: https://www.spicyapi.com/api/mcp (Streamable HTTP, stateless).

Install

Claude Code

claude mcp add --transport http spicyapi https://www.spicyapi.com/api/mcp --header "Authorization: Bearer sk-spicy-..."

Or leave the header off and run /mcp to sign in with OAuth.

Cursor

{
  "mcpServers": {
    "spicyapi": {
      "url": "https://www.spicyapi.com/api/mcp",
      "headers": { "Authorization": "Bearer sk-spicy-..." }
    }
  }
}

Codex

[mcp_servers.spicyapi]
url = "https://www.spicyapi.com/api/mcp"
bearer_token_env_var = "SPICYAPI_KEY"

Claude custom connectors, ChatGPT and other OAuth clients

Paste the URL https://www.spicyapi.com/api/mcp and nothing else. The client discovers the authorization server, opens /oauth/authorize, and the user signs in (or creates the account there) and clicks Allow. OAuth 2.1 with dynamic client registration and PKCE; no client secret.

Two ways to authenticate, one kind of credential

API key: Authorization: Bearer sk-spicy-..., the same keys as the REST API, from /dashboard/api-keys.
OAuth 2.1: metadata at https://www.spicyapi.com/.well-known/oauth-authorization-server, registration at POST https://www.spicyapi.com/oauth/register, token at POST https://www.spicyapi.com/oauth/token (authorization_code with PKCE S256). The access token it returns is an API key named "OAuth: <app>", so it shows up in the dashboard and is revoked there. On the consent screen the user can tick "Sandbox only" to grant a token that can never spend.

Tools

Tool	What it does	Needs approval
`list_models`	Models with prices, limits and example clips	no
`estimate_cost`	Price a request from the billing table	no
`get_account`	Balance, month-to-date spend, spend limit	no
`list_images`	The account's generated images (valid inputs for edits and video)	no
`list_characters`	Saved characters: reusable identities built from the account's own images	no
`create_character`	Build a character from 1 to 3 generated images (billed as one edit)	yes
`delete_character`	Remove a character (its sheet stays in the library)	yes
`generate_image`	Text to image, or an image action (the woman from your image in a ready-made explicit still), returns CDN URLs	yes
`edit_image`	Prompt-driven edit of the account's own images	yes
`generate_video`	Image to video or text to video (first and last frame, references, clip extension, audio, smart duration, draft tier, Cinema engine), returns a task	yes
`edit_video`	Edit one of the account's clips from a prompt and reference images, or transfer a motion clip onto a person (motion transfer), returns a task	yes
`list_motions`	The curated motion clips for motion transfer	no
`list_actions`	The curated sex act reference clips for `generate_video` with `action`	no
`list_image_actions`	The curated explicit stills for `generate_image` with `action` on `spicy-image-action-1`	no
`list_styles`	The art styles for `style` on `generate_image` and `generate_video` (photorealistic, studio, anime, 3d, cartoon)	no
`upload_audio`	Fetch, transcribe and screen a WAV or MP3 from a URL for lip-sync video ($0.01)	yes
`list_audio`	The account's screened audio clips (valid `audio_url` values)	no
`delete_audio`	Forget an uploaded clip	yes
`generate_speech`	Text to speech as a WAV or MP3 URL (inline emotion and sound tags on Spicy Voice 2), usable as `audio_url` on video	yes
`transcribe_audio`	Speech to text from an audio URL, billed by the second	yes
`create_embeddings`	Text or image embeddings for search, memory and dedupe	yes
`list_voices`	Preset voices per speech model and the account's designed and cloned voices	no
`create_voice`	Clone a voice from a clip with the speaker's consent (design is paused)	yes
`delete_voice`	Delete a designed or cloned voice	yes
`get_job`	Poll a video task	no
`list_jobs`	Recent requests with status and cost	no
`get_usage`	Calls and cost by model over N days	no
`create_api_key`	Mint a key (live or sandbox), shown once	yes
`revoke_api_key`	Revoke a key	yes
`get_topup_link`	Checkout URL (card or crypto) for the user to pay in the browser	no
`set_spend_limit`	Monthly cap enforced at debit time	raising it, yes
`read_acceptable_use`	The acceptable use policy as markdown	no

Every tool carries readOnlyHint, destructiveHint and openWorldHint annotations. The same tools are plain REST at POST https://www.spicyapi.com/api/v1/tools/{tool_name} (list with GET https://www.spicyapi.com/api/v1/tools), described in /openapi.json.

Approvals

A guarded tool called without approval_token spends nothing and returns:

{"error": "approval_required", "summary": "Generate 1 image on spicy-image-1 for $0.06", "approval_token": "...", "expires_in_seconds": 900}

The agent shows the summary to the user, gets a yes, and calls again with the same arguments plus the token. Tokens are bound to the account, the tool and the exact arguments, and expire in 15 minutes. Accounts that run agents unattended can turn approvals off at /dashboard/api-keys; moderation, provenance, balance and the spend limit still apply.

Sandbox

A sandbox key (tick Sandbox when creating a key, or on the OAuth consent screen) answers every tool and every REST endpoint from fixtures flagged sandbox: true. Nothing is generated or billed and no balance is needed. Build against it, then swap the key.

A first prompt to try

Use the spicyapi tools. Read the acceptable use policy, list the video models with prices, estimate 10 five-second clips at 720P, and tell me what it would cost. Do not generate anything yet.

Paying

The agent never handles payment details. get_topup_link returns a hosted checkout URL (minimum $50); the user pays in the browser; get_account confirms the new balance.

Skills

Ready-made SKILL.md workflows (integrate the API, image to video, voices and speech, control spend, choose a model): /skills/index.json, mirrored at https://github.com/Wayfinity/spicyapi-skills. Registry name: com.spicyapi/mcp.

Limits and logging

60 requests per minute per key. Each tool call is logged as tool name, key id, success or error code, latency and the sandbox flag. Prompts, arguments and outputs are never stored in that log.