choose-a-model

Imported from Wayfinity/spicyapi-skills (skills/choose-a-model/SKILL.md). Install upstream with npx skills add Wayfinity/spicyapi-skills --skill choose-a-model. Copyright stays with the author (MIT).

Choose a Spicy API model

When to use

The user has a generation job and wants the cheapest model that does it, or asks what a model can do.

How to choose

• Stills, volume or speed: spicy-image-1 (eleven 1K sizes at one price, up to 6 per call). Stills, best prompt adherence: spicy-image-1-pro. Stills that look like a real candid photo: spicy-image-photo-1. Explicit stills of a given woman in a sex act: spicy-image-action-1 with action from list_image_actions and her image. A picture the user supplies, as new people (businesses approved for character import only): spicy-image-reference-1 with reference_image.
• Change an existing image (outfit, pose, scene, combine up to 3 references, up to 6 variations): spicy-image-edit-1. Inputs must be the account's own generated images.
• Preview motion cheaply: spicy-motion-draft-1, a silent image-to-video draft tier at a quarter of the price; render the keeper on a full model.
• Animate a still, general scenes: spicy-motion-2 (720P or 1080P, 2 to 15 seconds, native audio, last frame, clip continuation, lip-sync audio). Newest, longer, with dialogue and effects, or text-to-video: spicy-motion-3 (480P to 1080P, up to 30 seconds or duration: -1 for a model-chosen length, references, clip extension, up to 5 audio clips, aspect ratios up to 21:9), spicy-motion-3-fast for faster turnaround at a higher rate. Cinematic camera work with native audio, lowest price at 480P: spicy-cinema-1 (text), spicy-cinema-1-image (first frame), spicy-cinema-1-character (up to 9 references kept consistent), 3 to 15 seconds. spicy-motion-1 and spicy-video-1 are the previous generation. Audio differs: driving audio (the clip is the soundtrack, mouth follows it, with a first frame) on spicy-motion-2 and spicy-video-1; reference audio (the model makes the sound, the clip sets voice, tone and beat, never with a first frame) on spicy-motion-3. inputs.combinations in list_models lists what each model takes together.
• Sex scenes with no motion prompt: spicy-motion-3 (or spicy-motion-3-fast) with action, one of 64 ready-made sex acts from list_actions. Pass an image of the woman (not a first frame in position) and optionally a scene prompt; the action's short reference clip (4 seconds on most) is billed as input seconds on top of the output, which defaults to 8 seconds.
• Change a finished clip (outfit from reference images, style, lighting, props): spicy-video-edit-1 (2 to 10 second clips) or spicy-cinema-1-edit (3 to 30 second clips, first 15 seconds returned), billed on input plus output seconds. Make a person dance or move like a clip: spicy-animate-1 with a library motion (list_motions), billed per output second; dressed performers only.
• Speech for a character, or a voiced line for video: spicy-voice-2 and spicy-voice-2-flash (inline emotion and sound tags, up to 5,000 characters, MP3 or streaming), spicy-voice-1 (most preset voices, cheapest), spicy-voice-1-expressive (preset voices plus instructions), spicy-voice-1-custom (voices the account designs or clones with create_voice). Billed per character; the returned url goes into generate_video as audio_url.
• A live spoken conversation with a companion: spicy-live-1 over a WebSocket (live-voice-calls skill).
• Chat: explicit role-play and companions: spicy-companion-1 (recommended; it stays in character and writes explicit adult scenes that spicy-chat-1 refuses), spicy-companion-1-flash for high-volume NPC traffic. General uncensored chat: spicy-chat-1. All through the OpenAI SDK, streaming included. Text only: max_tokens up to 8192, n up to 4, about 200k input tokens; no tools, thinking, search or json_schema.
• Voice notes to text: spicy-transcribe-1. Companion memory and search: spicy-embed-1 (text); spicy-embed-vision-1 for "more like this" over the account's own images.

Confirm with list_models (kind filter) for the live limits and example clips, and price the job with estimate_cost. Default video resolution is 720P; 1080P costs more per second.

Models and prices

Tools used by this skill

• list_models: Every model with its kind (image, image-edit, video, video-edit, chat, speech, realtime, transcription, embedding), USD price (per image, per second by resolution or quality, per 1M tokens, per 10,000 characters of speech input, or per minute of audio), limits (image sizes, outputs per call, resolutions, clip lengths, aspect ratios, prompt character caps), whether it needs or accepts an input image or references, and example clips. Video rows carry inputs: which of first frame, last frame, reference images, clip and audio the model takes, inputs.audio.mode (driving: the clip is the soundtrack and the mouth follows it; reference: the model generates sound and uses the clip for voice, tone and beat; none) and inputs.combinations, the valid input combinations in plain sentences. Read those before generate_video. silent: true marks a video model that renders without sound; bills_input_video_seconds: true one that also bills the seconds of an input clip. Video-edit rows carry video_edit (instruction or motion mode, clip lengths, reference images, whether input seconds are billed) for edit_video. Speech rows carry speech: preset voices, whether instructions are accepted, custom voices, languages, inline tags and voice creation fees. Realtime rows (spicy-live-1) are live voice calls over a WebSocket: a server or app opens a session with POST /v1/realtime/sessions and connects the returned ticket URL; they cannot be driven from a tool call. Prices here are exactly what the API bills. Works with a $0 balance. Arguments: kind?: image | image-edit | video | video-edit | chat | speech | realtime | transcription | embedding (Filter by kind.).
• estimate_cost: USD cost of a request before making it, from the same price table the gateway bills: images by count, video by seconds and resolution (plus the input clip or action clip on models that bill it), video edits by clip length (input plus output seconds for instruction edits, output seconds for motion transfer), chat by tokens, speech by characters of input (plus instructions), transcription by seconds of audio, embeddings by tokens, live calls by minutes. Use it to quote the user and to check against get_account before a spend. Works with a $0 balance. Arguments: model: string (A model id from list_models, e.g. spicy-image-1, spicy-image-1-pro, spicy-image-photo-1.); n?: integer (Images per call (image models), clamped to the model's maximum.); resolution?: string (Video or video-edit resolution, e.g. 720P (default) or 1080P.); quality?: standard | pro (Motion transfer tier on spicy-animate-1, default standard.); duration?: integer (Video seconds, default 5; -1 for a model-chosen length where supported.); input_seconds?: number (Length of the input clip in seconds: the clip to edit or motion clip on video-edit models (default 5), or a video_url on video models that bill input seconds.); motion?: string (A library motion id (list_motions) on spicy-animate-1; its length sets the output length.); action?: string (An action id (list_actions) on spicy-motion-3 and -fast: its reference clip seconds (4 on most) are billed as input, and duration defaults to 8.); fps?: any (Video frame rate: 30 (default) or 60. 60 smooths motion with frame interpolation for 20% on top of the video price (input or action clip seconds included); audio is kept. If that step fails the 30 fps clip is delivered and the fee refunded.); tokens?: integer (Chat: total tokens, default 1000. Embeddings: text tokens, default 1000.); image_tokens?: integer (Embeddings on spicy-embed-vision-1: image tokens, default 0.); characters?: integer (Speech models: characters of input plus instructions (CJK ideographs and inline tags count too), default 100.); audio_seconds?: number (Transcription: seconds of audio, default 60.); minutes?: number (Live calls (spicy-live-1): minutes of conversation, default 1.); count?: integer (How many such requests, default 1.).
• list_motions: The motion library for motion transfer on edit_video (spicy-animate-1): id, label, description, preview url, duration_s and aspect_ratio of each clip. Every clip is 9:16, full body, fixed camera and was generated with SpicyAPI video models (no real performer footage). The output is as long as the clip; match the performer image to its framing for best results. Works with a $0 balance. Arguments: no arguments.
• list_actions: The action library for generate_video with action (spicy-motion-3 and spicy-motion-3-fast): id, label, category (sex, anal, oral, handjob, cumshot, solo, trans), url (the reference clip, 4 to 6 seconds), preview_url (the full 8 second action), poster_url, duration_s (the reference clip's length) and aspect_ratio. The clip supplies the camera, pose and motion of one sex act; the output runs 8 seconds by default and carries the act on past the clip. The caller's image supplies the woman. Every clip was generated with SpicyAPI video models (no real performer footage). Its seconds are billed as input seconds. Works with a $0 balance. Arguments: no arguments.
• list_image_actions: The image action library for generate_image on spicy-image-action-1: id, label, category (sex, anal, oral, handjob, cumshot, solo, trans), image_url (the still), preview_url (a small copy), size (the output width*height) and styles (the still redrawn as anime, 3d and cartoon, for style on a drawn woman). 68 ready-made explicit stills; most share their id with a video action (list_actions). The still supplies the act, pose, framing, room and her body; the caller's image supplies her face, hair and skin tone. Every still was generated with AI (no real performers). Billed per image at the model's rate. Works with a $0 balance. Arguments: no arguments.
• read_acceptable_use: The acceptable use policy as markdown: prohibited content (minors in any form, images or video of real people with or without consent, non-consensual scenarios and the rest), age-verification duties for the customer's product, enforcement. Read it before the first generation and tell the user what their product must do. Works with a $0 balance. Arguments: no arguments.

Setup (once per user)

1. Key: the user signs in once at https://www.spicyapi.com/auth (Google or email). The account is live at once with a $0 balance and a Default key shown once at https://www.spicyapi.com/dashboard/api-keys. Keep the key in an environment variable (SPICYAPI_KEY), never in chat, never in client-side code. With one key you can mint more with create_api_key.
2. Connect. MCP (Streamable HTTP): https://www.spicyapi.com/api/mcp with header Authorization: Bearer <key>. Claude Code: claude mcp add --transport http spicyapi https://www.spicyapi.com/api/mcp --header "Authorization: Bearer sk-spicy-...". Cursor, Codex and any URL-plus-headers client: same URL and header. REST instead of MCP: POST https://www.spicyapi.com/api/v1/tools/<tool_name> with the same header and a JSON body of arguments; GET https://www.spicyapi.com/api/v1/tools lists them; OpenAPI 3.1 at https://www.spicyapi.com/openapi.json. OAuth 2.1 clients (Claude custom connectors, ChatGPT, directory scanners) need only the URL: the endpoint advertises its authorization server, the user signs in and consents in the browser, and the token it returns is an API key they can revoke in the dashboard.
3. Dry run first: a key created with Sandbox ticked (or create_api_key with sandbox: true) answers every endpoint and every tool from fixture output flagged sandbox: true, needs no balance and bills nothing. Build against it, then swap the key. Never present sandbox output to the user as a real generation.
4. Money: get_account shows the balance; estimate_cost prices a request from the same table the API bills; get_topup_link returns a card or crypto checkout URL (presets $50, $100, $250, $500, $1000, minimum $50) that the USER opens and pays in the browser. Never enter card details yourself. A 402 means the balance ran out or the monthly limit was hit.
5. Rate limit: 60 requests per minute per key on the agent surfaces.

Rules that always apply

• Guarded tools (generate_image, edit_image, generate_video, edit_video, transcribe_audio, create_embeddings, upload_audio, delete_audio, generate_speech, create_voice, delete_voice, create_character, delete_character, create_api_key, revoke_api_key, and set_spend_limit when raising or removing a limit) first return {error: "approval_required", summary, approval_token}. Show the summary to the user verbatim (it carries the cost), get an explicit yes in the conversation, then call the tool again with the same arguments plus approval_token (15-minute expiry, bound to those exact arguments). Never approve in bulk or reuse a token for a different action. The account can turn approvals off in the dashboard; moderation, provenance and the spend limit still apply.
• Input images for edit_image, generate_video, edit_video and create_embeddings must be images this account generated (list_images); input clips (video_url) must be the account's own finished tasks. Uploads and third-party URLs are rejected before any charge; do not try to work around it. The external inputs are audio: upload_audio takes a WAV or MP3 (2 to 30 seconds) from a public URL, transcribes and screens it for $0.01, and its returned url, or the url of a generate_speech clip, is what audio_url accepts; transcribe_audio reads any public audio URL into text.
• The same person across many outputs: create_character from 1 to 3 generated images of them, then pass the returned id as character to generate_image, edit_image or generate_video (spicy-character-video-1 needs no first frame). This is the supported way to get consistency; never ask the user for a photo.
• Read read_acceptable_use before the first generation: adults only, no minors in any form (including "young-looking" or youth-coded content), no images or video of real people (with or without consent; voice clones need the speaker's written consent), no non-consensual scenarios. Blocked prompts return 422 and cost nothing; repeated attempts terminate the account. Tell the user their product must age-verify its end users and disclose that content is AI-generated.
• When the user's product serves other people, pass each person's own stable id as user on every call. Screening history, strikes and suspensions then apply to that one person (403 end_user_suspended) instead of the whole account, and the id is kept with each generation's record, so a report about one person's output is traced to them and not to everyone on the account.
• Everything is scoped to the account behind the key; there is no way to read another account's data.
• Spicy API is spicyapi.com. spicyapi.ai is an unrelated aggregator; do not mix their prices or models.

Prices (USD, for when the user asks)

Public docs: https://www.spicyapi.com/docs (every page is also available as markdown by appending .md). Product overview for agents: https://www.spicyapi.com/llms.txt