{"openapi":"3.1.0","info":{"title":"SpicyGen API","version":"1.0.0","description":"AI adult image, character and movie generator for adults. Create characters, generate images and videos, build movies, manage the library and buy credits, for the account that owns the API key. This REST surface mirrors the MCP server one to one; the same key works for both. Every call runs the same moderation, credit, suspension and age-gate checks as the website; nothing here can exceed what the account can do in the browser. Credit-spending tools are guarded by an approval round trip. Adults only."},"servers":[{"url":"https://www.spicygen.ai"}],"x-mcp":{"endpoint":"https://www.spicygen.ai/api/mcp","transport":"streamable-http","auth":"Authorization: Bearer sg_live_…","docs":"https://www.spicygen.ai/docs/agents","llms":"https://www.spicygen.ai/llms.txt","skills":"https://www.spicygen.ai/skills/index.json"},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"sg_live_… or sg_sandbox_…","description":"Per-user API key from https://www.spicygen.ai/account#api-keys. Sandbox keys answer from fixtures and spend nothing."}}},"tags":[{"name":"default","description":"Reads and reversible writes."},{"name":"guarded","description":"Spends credits or deletes. Approval round trip unless the account skips approvals."}],"paths":{"/api/v1/tools":{"get":{"operationId":"listTools","summary":"List every tool with its argument schema and whether it is guarded. No key needed.","security":[],"responses":{"200":{"description":"Tool catalog","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/tools/get_account":{"post":{"operationId":"get_account","summary":"Get account","description":"Start here. Credits balance, age-verification state for the caller's jurisdiction (whether NSFW media is available, and the verification URL when it is not), credit costs per image, per video second and per character, rate limits, and whether the account skips approvals.","tags":["default"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/read_content_rules":{"post":{"operationId":"read_content_rules","summary":"Read content rules","description":"The acceptable-use rules every prompt and image is checked against (adults only, fictional characters only, no real people, no minors, no non-consent, no violence). Read this before writing prompts; a blocked prompt costs nothing and is logged; serious or repeated abuse can get the account suspended.","tags":["default"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/list_characters":{"post":{"operationId":"list_characters","summary":"List characters","description":"The user's saved characters (id, name, appearance, style, status, thumbnail). Use a character id in generate_images, generate_video and create_movie_scene for a consistent identity.","tags":["default"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/get_character":{"post":{"operationId":"get_character","summary":"Get character","description":"One character with its recent generations (images and videos). NSFW media URLs are withheld when the account's jurisdiction requires age verification the user has not completed.","tags":["default"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"character_id":{"type":"string","minLength":1,"description":"An id from list_characters."}},"required":["character_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/create_character":{"post":{"operationId":"create_character","summary":"Create character","description":"Create a reusable character from a text description (10 credits). Generates the identity image; poll get_character until status is ready (about a minute). The description goes through the same prompt moderation as the website. GUARDED: without approval_token (or the account's skip-approvals setting) it returns 402 {error:\"approval_required\", summary, credits, approval_token}; call again with the token after the user said yes.","tags":["guarded"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"description":"Display name, up to 40 characters."},"appearance":{"type":"string","minLength":10,"maxLength":2000,"description":"Appearance: body, face, hair, age (adults only), clothing, setting. 10 to 2000 characters."},"style":{"description":"Art style. Default Photorealistic.","type":"string","enum":["Photorealistic","Studio","Hentai (Anime)","3D","Cartoon"]},"approval_token":{"description":"Approval token from a previous approval_required response, after the user said yes.","type":"string"}},"required":["name","appearance"],"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/generate_images":{"post":{"operationId":"generate_images","summary":"Generate images","description":"Generate 1 to 10 images from a prompt (credits each: 5 SpicyImage 1, 10 SpicyImage 2, 11 SpicyImage 2.1; a character reference needs SpicyImage 2 or 2.1). Returns job ids; poll get_job. Prompts are moderated exactly as on the website; call read_content_rules first. GUARDED: without approval_token (or the account's skip-approvals setting) it returns 402 {error:\"approval_required\", summary, credits, approval_token}; call again with the token after the user said yes.","tags":["guarded"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":2000,"description":"The scene, up to 2000 characters."},"character_id":{"description":"Generate this saved character (from list_characters). Omit for a new subject.","type":"string"},"count":{"description":"Number of images, default 1.","type":"integer","minimum":1,"maximum":10},"quality":{"description":"Image model: Standard = SpicyImage 1 (default), HD = SpicyImage 2, 2.1 Pro = SpicyImage 2.1 (newest). Prices in get_account.costs.image. A character reference needs HD or 2.1 Pro.","type":"string","enum":["Standard","HD","2.1 Pro"]},"ratio":{"description":"Aspect ratio. Default 1:1 for images, 9:16 for video.","type":"string","enum":["1:1","16:9","9:16","4:3","3:4"]},"style":{"description":"Art style. Default Photorealistic.","type":"string","enum":["Photorealistic","Studio","Hentai (Anime)","3D","Cartoon"]},"approval_token":{"description":"Approval token from a previous approval_required response, after the user said yes.","type":"string"}},"required":["prompt"],"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/generate_video":{"post":{"operationId":"generate_video","summary":"Generate video","description":"Turn a library image (source_item_id) or a character (character_id) into a video with a motion prompt. Costs 10 to 20 credits per second depending on quality and model (see get_account.costs). Returns a job id; poll get_job (videos take a few minutes). GUARDED: without approval_token (or the account's skip-approvals setting) it returns 402 {error:\"approval_required\", summary, credits, approval_token}; call again with the token after the user said yes.","tags":["guarded"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":2000,"description":"What happens in the video."},"source_item_id":{"description":"A library image id (from list_library or get_job) to animate.","type":"string"},"character_id":{"description":"A character id to animate when no source image is given.","type":"string"},"seconds":{"description":"Length in seconds, default 5. v3 allows up to 15, v3-fast up to 30.","type":"integer","minimum":3,"maximum":30},"quality":{"description":"Standard or HD. HD costs more (see get_account.costs). Images with a character reference are always HD.","type":"string","enum":["Standard","HD"]},"ratio":{"description":"Aspect ratio. Default 1:1 for images, 9:16 for video.","type":"string","enum":["1:1","16:9","9:16","4:3","3:4"]},"model":{"description":"SpicyMotion v3.0 (default) or v3.0 Fast (native audio, up to 30 seconds, higher per-second price).","type":"string","enum":["v3","v3-fast"]},"audio":{"description":"Generate audio (v3-fast only).","type":"boolean"},"approval_token":{"description":"Approval token from a previous approval_required response, after the user said yes.","type":"string"}},"required":["prompt"],"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/create_movie_scene":{"post":{"operationId":"create_movie_scene","summary":"Create movie scene","description":"Add a scene to a movie and start generating it on SpicyMotion v3.0 Fast (HD, audio). Omit movie_id to start a new movie; the first scene needs a source_item_id or character_id, later scenes continue from the previous scene's last frame. Costs 20 credits per second. Poll get_job with the returned job id; when it completes, call create_movie_scene again for the next scene, then combine_movie. GUARDED: without approval_token (or the account's skip-approvals setting) it returns 402 {error:\"approval_required\", summary, credits, approval_token}; call again with the token after the user said yes.","tags":["guarded"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"movie_id":{"description":"An existing movie id to append to. Omit to create a new movie.","type":"string"},"title":{"description":"Title for a new movie.","type":"string","maxLength":80},"prompt":{"type":"string","minLength":3,"maxLength":2000,"description":"What happens in this scene."},"seconds":{"description":"Scene length, default 5.","type":"integer","minimum":3,"maximum":30},"source_item_id":{"description":"Library image to open the movie with (first scene only).","type":"string"},"character_id":{"description":"Character to open the movie with (first scene only).","type":"string"},"ratio":{"description":"Aspect ratio. Default 1:1 for images, 9:16 for video.","type":"string","enum":["1:1","16:9","9:16","4:3","3:4"]},"approval_token":{"description":"Approval token from a previous approval_required response, after the user said yes.","type":"string"}},"required":["prompt"],"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/combine_movie":{"post":{"operationId":"combine_movie","summary":"Combine movie","description":"Stitch a movie's completed scenes into one video (no credits, but it renders on the server and is guarded so the user confirms the cut). Returns the movie URL. GUARDED: without approval_token (or the account's skip-approvals setting) it returns 402 {error:\"approval_required\", summary, credits, approval_token}; call again with the token after the user said yes.","tags":["guarded"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"movie_id":{"type":"string","minLength":1},"approval_token":{"description":"Approval token from a previous approval_required response, after the user said yes.","type":"string"}},"required":["movie_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/get_job":{"post":{"operationId":"get_job","summary":"Get job","description":"Status of a generation job (queued, generating, completed, failed), progress, and on completion the image or video URLs (withheld with nsfw_withheld:true when the age gate applies). Poll every 10 to 20 seconds.","tags":["default"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","minLength":1,"description":"A job id returned by generate_images, generate_video or create_movie_scene."}},"required":["job_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/list_library":{"post":{"operationId":"list_library","summary":"List library","description":"The user's generated images and videos, newest first, with prompt, status, favourite flag and URLs (NSFW withheld when the age gate applies). Paginate with cursor.","tags":["default"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"description":"Default all.","type":"string","enum":["images","videos","all"]},"favorites_only":{"type":"boolean"},"limit":{"description":"Default 20.","type":"integer","minimum":1,"maximum":50},"cursor":{"description":"next_cursor from a previous page.","type":"string"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/favorite_item":{"post":{"operationId":"favorite_item","summary":"Favourite item","description":"Mark or unmark a library item as a favourite.","tags":["default"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"item_id":{"type":"string","minLength":1},"favorite":{"description":"Default true; false removes the favourite.","type":"boolean"}},"required":["item_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/delete_item":{"post":{"operationId":"delete_item","summary":"Delete item","description":"Delete a library image or video. Irreversible; guarded so the user confirms. GUARDED: without approval_token (or the account's skip-approvals setting) it returns 402 {error:\"approval_required\", summary, credits, approval_token}; call again with the token after the user said yes.","tags":["guarded"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"item_id":{"type":"string","minLength":1},"approval_token":{"description":"Approval token from a previous approval_required response, after the user said yes.","type":"string"}},"required":["item_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/get_credit_packs":{"post":{"operationId":"get_credit_packs","summary":"Get credit packs","description":"Credit packs and prices available to this account (regional packs where they apply), with what each pack buys in images and video seconds.","tags":["default"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/get_checkout_link":{"post":{"operationId":"get_checkout_link","summary":"Get checkout link","description":"A hosted checkout URL for a credit pack. Hand the URL to the user; they pay in their browser (card, local methods or crypto depending on region). Never ask for or enter card details. Credits land in the account when the provider confirms; get_account shows the new balance.","tags":["default"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pack_id":{"type":"string","minLength":1,"description":"A pack id from get_credit_packs."}},"required":["pack_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}},"/api/v1/tools/get_referral_stats":{"post":{"operationId":"get_referral_stats","summary":"Get referral stats","description":"The user's referral code and link, referred signups, clicks and credits earned. Affiliate program payouts (Tapfiliate) are read in the affiliate dashboard, not here.","tags":["default"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The tool's JSON result (same payload the MCP tool returns).","content":{"application/json":{"schema":{}}}},"400":{"description":"Arguments failed validation; body lists the issues."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Guarded tool without an approval token, or insufficient credits."},"429":{"description":"Rate limited (60 requests per minute per key)."}}}}}}