{"openapi":"3.1.0","info":{"title":"Cleus API","version":"1.1.0","description":"Uncensored chat, 8 image models, 7 video models, speech, voice cloning, music, roleplay characters and long-form stories. Every endpoint mirrors a tool of the Cleus MCP server (api.cleus.ai/mcp). Slow jobs answer 202 with an id: poll GET /v1/jobs/{id}."},"servers":[{"url":"https://api.cleus.ai/v1"}],"security":[{"bearer":[]}],"paths":{"/agent":{"post":{"operationId":"postAgent","summary":"Hand a task to the Cleus Agent: web research, files, code, ~1,450 specialist models.","tags":["Text"],"description":"Hand a task to the Cleus Agent, which plans and uses its own tools: live web search and deep research, reading any URL, X/Twitter search, stock and crypto analysis, running Python in a sandbox, analysing CSV/XLSX data, creating PDF / DOCX / XLSX / slide / chart files, memes, image analysis — and finding and running any of ~1,450 specialist AI models (sound effects, 3D models from images, background removal, upscalers, lip sync, style transfer…) or asking any of ~450 other LLMs. Use it for things the other Cleus tools don’t cover. Model runs above $1 are confirmed first: reply \"yes\" with the same history to go ahead. Billed at chat rates plus each tool’s own price. Returns text with links to any files and media it made; resume \"processing\" with cleus_get_result.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"string","description":"What to do, with any URLs and details it needs."},"history":{"type":"array","description":"Optional earlier turns, oldest first.","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}},"required":["role","content"]}},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["task"]}}}}}},"/images/generations":{"post":{"operationId":"postImagesGenerations","summary":"Generate images with any of the 8 image models, or of one of your Avatars with avatar_id (OpenAI-shaped response).","tags":["Images"],"description":"Generate images from a text prompt with any Cleus image model. Models: uncensored (Uncensored+: No filter, allows explicit (adults only), realistic photos and readable text; $0.09/image, edits $0.12); quality (Quality+: Fast, cheap and sharp; good default; allows explicit; $0.09/image, edits $0.12); pro (Pro+: Most detailed and photoreal, up to 2K; $0.36/image, edits $0.36); nano-banana-2.1 (Nano Banana 2.1: Precise edits, readable text, character consistency; $0.12/image, edits $0.12); gpt-image-2.5 (GPT Image 2.5: Posters, logos, UI mockups, typography; $0.27/image, edits $0.27); grok-imagine (Grok Imagine 2.0: Real public figures and celebrities; $0.24/image, edits $0.24); nano-banana-pro (NanoBanana Pro: Careful, safe-for-work edits; $0.09/image, edits $0.30); flux-2 (Flux 2: Cheap square images and quick edits; $0.06/image, edits $0.14). Pick by need: quality for most things, pro for photoreal detail, gpt-image-2.5 or nano-banana-2.1 for text/logos/UI, grok-imagine for real public figures, uncensored for adult content. To change or combine existing images use cleus_edit_image. Returns hosted image URLs.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"What to draw: subject, composition, style, lighting, any text to render (in quotes)."},"model":{"type":"string","enum":["uncensored","quality","pro","nano-banana-2.1","gpt-image-2.5","grok-imagine","nano-banana-pro","flux-2"],"default":"quality"},"n":{"type":"integer","minimum":1,"maximum":4,"default":1,"description":"Number of images."},"aspect_ratio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4"],"default":"1:1","description":"Ignored by flux-2 (always square)."},"avatar_id":{"type":"string","description":"Put one of the user's Cleus Avatars (their face) in the image — ids from cleus_list_avatars. Replaces `model`; never explicit."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["prompt"]}}}}}},"/images/edits":{"post":{"operationId":"postImagesEdits","summary":"Edit or combine up to 4 images by instruction (OpenAI-shaped response).","tags":["Images"],"description":"Edit images with a text instruction, or combine several reference images into a new one: change backgrounds, outfits, lighting or style, remove or add objects, put a product into a scene, keep a character consistent across shots, merge people from several photos. Up to 4 input images (public URLs or cleus_upload_file URLs). Models: quality, pro, nano-banana-2.1, gpt-image-2.5, grok-imagine, nano-banana-pro, flux-2 (quality is the default and also handles adult content). Each result costs the model’s edit price.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_urls":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":4,"description":"Input images. Refer to them in the prompt as image 1, image 2…"},"prompt":{"type":"string","description":"The edit, e.g. \"put the sneaker from image 1 on wet asphalt at night, neon reflections\"."},"model":{"type":"string","enum":["quality","pro","nano-banana-2.1","gpt-image-2.5","grok-imagine","nano-banana-pro","flux-2"],"default":"quality"},"aspect_ratio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4"],"description":"Output shape (pro, nano-banana-2.1, gpt-image-2.5, grok-imagine only; others keep the input shape)."},"n":{"type":"integer","minimum":1,"maximum":4,"default":1,"description":"Number of variations."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["image_urls","prompt"]}}}}}},"/images/upscale":{"post":{"operationId":"postImagesUpscale","summary":"Upscale an image 4× with face enhancement.","tags":["Images"],"description":"Upscale an image 4× with face enhancement (sharper details, clean faces). Inputs over 1.5 megapixels are first shrunk to fit. Free.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","description":"Public URL of the image (or a cleus_upload_file URL)."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["image_url"]}}}}}},"/images/remove-background":{"post":{"operationId":"postImagesRemoveBackground","summary":"Cut the subject out onto a transparent PNG.","tags":["Images"],"description":"Cut out the subject of an image onto a transparent background (PNG). Great for product shots, sprites, stickers and logos. $0.04 per image.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","description":"Public URL of the image (or a cleus_upload_file URL)."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["image_url"]}}}}}},"/images/inpaint":{"post":{"operationId":"postImagesInpaint","summary":"Repaint the white area of a mask.","tags":["Images"],"description":"Repaint only the masked part of an image: mask_url is a black-and-white image the same size as the source, white = area to change. Use when an edit must not touch anything else. engine: nano-banana-2 (default) or flux-2. $0.36 per edit. For edits that don’t need pixel-exact masks, cleus_edit_image is cheaper.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","description":"Public URL of the image (or a cleus_upload_file URL)."},"mask_url":{"type":"string","description":"Mask image URL (white = repaint, black = keep)."},"prompt":{"type":"string","description":"What should appear in the masked area."},"engine":{"type":"string","enum":["nano-banana-2","flux-2"],"default":"nano-banana-2"},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["image_url","mask_url","prompt"]}}}}}},"/images/expand":{"post":{"operationId":"postImagesExpand","summary":"Outpaint beyond an image edge.","tags":["Images"],"description":"Extend an image beyond its edges in one direction (left, right, up or down), filling in matching scenery — e.g. turn a portrait shot into a wide banner. Call again to extend further. engine: nano-banana-2 (default) or flux-2. $0.36 per expansion.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","description":"Public URL of the image (or a cleus_upload_file URL)."},"direction":{"type":"string","enum":["left","right","up","down"],"default":"right"},"prompt":{"type":"string","description":"Optional: what the new area should contain."},"engine":{"type":"string","enum":["nano-banana-2","flux-2"],"default":"nano-banana-2"},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["image_url"]}}}}}},"/images/try-on":{"post":{"operationId":"postImagesTryOn","summary":"Put a garment from one photo on the person in another.","tags":["Images"],"description":"Dress a person in a garment: person_image_url (a clear photo of the person) + garment_image_url (the top/shirt/jacket on a plain background). Upper-body garments. $0.10 per image.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_image_url":{"type":"string"},"garment_image_url":{"type":"string"},"garment_description":{"type":"string","description":"Short description, e.g. \"red flannel shirt\"."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["person_image_url","garment_image_url"]}}}}}},"/images/describe":{"post":{"operationId":"postImagesDescribe","summary":"Detailed description / alt text for an image.","tags":["Images"],"description":"Get a detailed description of an image (subjects, setting, style, text in it) — handy as alt text, as a prompt to recreate it, or when your client cannot view images. Free.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","description":"Public URL of the image (or a cleus_upload_file URL)."}},"required":["image_url"]}}}}}},"/avatars":{"get":{"operationId":"getAvatars","summary":"Your Avatars — use one as avatar_id in /images/generations.","tags":["Images"],"description":"List the user's Cleus Avatars (made from their photos in Cleus Imagine) with ids and preview images. Use an id as avatar_id in cleus_generate_image, or a preview as the portrait for cleus_talking_video. Free.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"postAvatars","summary":"Make an Avatar from 3–10 photos of one person (free, about a minute).","tags":["Images"],"description":"Make a Cleus Avatar — a consistent face you can put in any image — from 3–10 photos of ONE person (close, well-lit, different angles; selfies work). The photos are checked (one clear face each, nobody under 18) and the clearest 3 are kept; it's ready in about a minute and free (5 a day). Then use cleus_generate_image { avatar_id } for new photos of them in any scene, or a preview as the portrait for cleus_talking_video. Only use photos of yourself or of someone who agreed to it. Avatar images are never explicit.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"photo_urls":{"type":"array","items":{"type":"string"},"minItems":3,"maxItems":10,"description":"Photos of the person (public URLs, uploads or job ids)."},"name":{"type":"string","description":"A name for the Avatar, e.g. \"Me\" or \"Maya\"."},"adults_confirmed":{"type":"boolean","description":"Must be true: everyone in the photos is 18 or older (and agreed to this)."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["photo_urls","name","adults_confirmed"]}}}}}},"/images/3d":{"post":{"operationId":"postImages3d","summary":"Turn an image of one object or character into a GLB 3D model.","tags":["Images"],"description":"Turn an image of one object or character into a textured 3D model (GLB) — for games, AR, 3D printing previews or product spins. Best with one subject on a plain background (make one with cleus_generate_image first, or cut it out with cleus_remove_background). quality \"fast\" ($0.06, ~30 s) or \"quality\" ($0.90, finer geometry and PBR textures, 1–4 min).","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","description":"The object or character (public URL, upload or job id)."},"quality":{"type":"string","enum":["fast","quality"],"default":"fast"},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["image_url"]}}}}}},"/images/vectorize":{"post":{"operationId":"postImagesVectorize","summary":"Convert an image to SVG, or generate SVG logos and icons.","tags":["Images"],"description":"Make scalable SVG vector art: image_url → convert a logo, icon or illustration to SVG; or prompt → generate SVGs (logos, icons, flat illustrations, stickers). Converting $0.2; generating $0.26 / $0.32 / $0.4 per SVG (quality low / medium / high).","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","description":"Image to convert (public URL, upload, job id or @asset)."},"mode":{"type":"string","enum":["default","simple"],"default":"default","description":"Converting: \"simple\" uses fewer, cleaner shapes."},"prompt":{"type":"string","description":"Generating: what to draw, e.g. \"minimal fox logo, two colors\"."},"quality":{"type":"string","enum":["low","medium","high"],"default":"medium"},"aspect_ratio":{"type":"string","enum":["auto","1:1","16:9","9:16","4:3","3:4","3:2","2:3"],"default":"auto"},"n":{"type":"integer","minimum":1,"maximum":4,"default":1},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}}}}}}}},"/templates":{"get":{"operationId":"getTemplates","summary":"One-tap photo and video effect templates.","tags":["Images"],"description":"Browse one-tap effect templates (like viral photo and video effects): action figure in a box, collectible figurine, 3D animated character, anime still, brick minifigure, plush toy, marble statue, 90s yearbook, studio product shot, movie poster, and video moves (360° orbit, Earth zoom-out, dolly zoom, melt, inflate), plus community templates. Returns ids, what photos each needs and its text inputs; run one with cleus_use_template. Free.","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["image","video"],"description":"Only image or video effects."}},{"name":"query","in":"query","required":false,"schema":{"type":"string","description":"Words to match, e.g. \"toy\" or \"zoom\"."}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/templates/run":{"post":{"operationId":"postTemplatesRun","summary":"Run an effect template on your photos.","tags":["Images"],"description":"Run an effect template from cleus_templates on the user's photo(s): fills in its prompt and runs it on the right model. Image effects cost one image edit (about $0.12–$0.36); video effects one 5–10 s video (about $1.58–$3.15). Pass inputs to change its text blanks (title, setting…). Same result, job id and get_cost as cleus_edit_image / cleus_generate_video. Only use photos of people who agreed to it.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template_id":{"type":"string","description":"Id from cleus_templates, e.g. \"action-figure\"."},"image_urls":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"The photo(s) it needs (public URLs, uploads or job ids)."},"inputs":{"type":"object","description":"Values for its text blanks, e.g. { \"title\": \"CAPTAIN CODE\" }."},"aspect_ratio":{"type":"string","description":"Override the output shape (e.g. \"9:16\")."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["template_id"]}}}}}},"/videos/generations":{"post":{"operationId":"postVideosGenerations","summary":"Text- or image-to-video with any of the 7 video models (async job).","tags":["Video"],"description":"Generate a video from a text prompt, or animate an image (image_url = first frame, end_image_url = last frame where supported). Models: quality (Quality+: Best all-rounder: 2–30 s, up to 1080p, native sound and dialogue, start + end frames; 2–30 s, 480p/720p/1080p; e.g. $1.41 for 5 s at 720p); uncensored (Uncensored+: No filter, allows explicit (adults only), 5 or 10 s, optional background music; 5 or 10 s, 480p/720p/1080p; e.g. $1.01 for 5 s at 720p); kling (Kling 4.0: Cinematic motion with sound, 3–30 s, 720p or 1080p, start + end frames; 3–30 s, 720p/1080p; e.g. $1.58 for 5 s at 720p); seedance (Seedance 2.5: Top detail, multi-shot scenes and dialogue, 4–15 s; 4–15 s, 480p/720p; e.g. $4.74 for 5 s at 720p); seedance-2 (Seedance 2.0: Reliable motion with native audio, 3–12 s, 720p, start + end frames; 3–12 s, 720p; e.g. $1.80 for 5 s at 720p); veo (Veo 3: Realistic footage with sound, 4 or 8 s; can be extended with cleus_extend_video; 4 or 8 s, 720p; e.g. $1.44 for 4 s at 720p); sora (Sora 2: Storytelling shots with sound, 4 or 8 s; 4 or 8 s, 720p; e.g. $1.20 for 4 s at 720p); grok-imagine (Grok Imagine Video: Real public figures, 1–15 s, up to 1080p, with sound; 1–15 s, 480p/720p/1080p; e.g. $1.44 for 5 s at 720p). Pick by need: quality for most clips (long, with dialogue and sound), kling or seedance for cinematic motion, veo or sora for realistic footage, grok-imagine for real public figures, uncensored for adult content. Videos take 1–5 minutes: the call waits ~45 s, then returns status \"processing\" and an id for cleus_get_result.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"What happens: subject, action, camera move, style, sound/dialogue (in quotes)."},"model":{"type":"string","enum":["quality","uncensored","kling","seedance","seedance-2","veo","sora","grok-imagine"],"default":"quality"},"image_url":{"type":"string","description":"Optional start frame (image-to-video)."},"end_image_url":{"type":"string","description":"Optional last frame (quality, kling, seedance, veo; needs image_url)."},"duration":{"type":"integer","minimum":1,"maximum":30,"description":"Seconds. Snapped to what the model supports (see model list)."},"resolution":{"type":"string","enum":["480p","720p","1080p"],"description":"Defaults to 720p; snapped to what the model supports."},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1","4:3","3:4","21:9","adaptive"],"default":"16:9","description":"Text-to-video shape; image-to-video follows the image."},"sound":{"type":"boolean","default":true,"description":"Native sound / dialogue (quality, seedance). kling, veo, sora and grok-imagine always have sound."},"seed":{"type":"integer","minimum":0,"description":"Reproducible results (quality, uncensored)."},"negative_prompt":{"type":"string","description":"What to avoid (uncensored only)."},"music_url":{"type":"string","description":"Background music MP3/WAV, 3–30 s (uncensored only)."},"n":{"type":"integer","minimum":1,"maximum":4,"default":1,"description":"Variations of this exact prompt and settings, each billed. For different prompts use cleus_generate_batch."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["prompt"]}}}}}},"/videos/edits":{"post":{"operationId":"postVideosEdits","summary":"Restyle/edit a video, or follow a reference clip (Kling 4.0).","tags":["Video"],"description":"Rework an existing video with Kling 4.0. mode \"edit\" (default): change the source video by instruction — restyle it (anime, claymation, film noir), swap the setting, change outfits or objects, relight it; the output keeps the source length and motion. mode \"reference\": make a NEW clip that follows a reference video’s motion/camera and/or reference images (characters, products, style). Refer to inputs in the prompt as @Video1 and @Image1, @Image2… Source video: https URL, 3–30 s, at least 720p, 24–60 fps. Price per second of input + output: $0.19 at 720p, $0.28 at 1080p (an edit bills about 2× the source length): a 5 s edit at 720p ≈ $1.89.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"The edit, e.g. \"turn @Video1 into a hand-painted watercolor, keep the camera move\"."},"video_url":{"type":"string","description":"Source / reference video (https). Required for mode \"edit\"."},"image_urls":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Optional reference images (@Image1…)."},"mode":{"type":"string","enum":["edit","reference"],"default":"edit"},"resolution":{"type":"string","enum":["720p","1080p"],"default":"720p"},"duration":{"type":"integer","minimum":3,"maximum":30,"default":5,"description":"Output length for mode \"reference\" (an edit keeps the source length)."},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1","21:9","auto"],"default":"16:9","description":"Mode \"reference\" only."},"video_seconds":{"type":"number","description":"Length of the source video if you know it (for the price check)."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["prompt"]}}}}}},"/videos/swap":{"post":{"operationId":"postVideosSwap","summary":"Put the person from a photo into a video’s exact motion.","tags":["Video"],"description":"Put the person (or character) from a photo into a video: they copy the video’s exact motion, expressions and camera, and the original sound is kept (motion control). Great for dance trends, reaction clips, mascots and \"me as…\" edits. person_image_url = clear photo of the person; video_url = the clip to copy (https, 3–30 s; 3–10 s with match \"image\"). Tiers per second of video: draft $0.46/s (renders only the first 5 s — preview first), standard $0.78/s, pro $1.04/s (best faces). Only use photos of people who agreed to it.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_image_url":{"type":"string","description":"Photo of the person/character to put in the video."},"face_image_urls":{"type":"array","items":{"type":"string"},"maxItems":3,"description":"Optional extra face close-ups for better likeness (standard/pro, match \"video\")."},"video_url":{"type":"string","description":"The video whose motion to copy (https)."},"tier":{"type":"string","enum":["draft","standard","pro"],"default":"standard"},"match":{"type":"string","enum":["video","image"],"default":"video","description":"\"video\" keeps the video’s framing and background; \"image\" keeps the photo’s."},"prompt":{"type":"string","description":"Optional: the setting/background, e.g. \"on a rooftop at sunset\"."},"keep_sound":{"type":"boolean","default":true},"video_seconds":{"type":"number","description":"Length of the video if you know it (for the price check)."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["person_image_url","video_url"]}}}}}},"/videos/extend":{"post":{"operationId":"postVideosExtend","summary":"Extend a Veo video by ~7 seconds.","tags":["Video"],"description":"Continue a Veo video (made with cleus_generate_video model \"veo\") by about 7 more seconds, following an optional prompt. Chain calls for longer shots. $2.10 per extension.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","description":"The Veo video to continue (https)."},"prompt":{"type":"string","description":"What happens next. Defaults to continuing the scene naturally."},"vertical":{"type":"boolean","default":false,"description":"true for 9:16 videos."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["video_url"]}}}}}},"/videos/talking":{"post":{"operationId":"postVideosTalking","summary":"A portrait speaks a script (21 voices) or your audio — lip-synced, up to 60 s.","tags":["Video"],"description":"Make a person in a photo speak: a lip-synced talking video (presenter, explainer, UGC ad, character message) from a portrait plus either a script (`text` + a presenter `voice`) or your own audio (`audio_url`, e.g. from cleus_clone_voice or cleus_generate_speech). Up to 60 seconds. quality: standard (Good lip sync at the lowest price), pro (Sharper detail and more accurate lips), ultra (Most natural face, head and body movement). Voices — female: Sarah, Jessica, Laura, Bella, Matilda, Alice (UK), Lily (UK); male: Liam, Will, Eric, Chris, Brian, Roger, Adam, Bill, Callum, Harry, George (UK), Daniel (UK), Charlie (AU); neutral: River. Per second of speech: standard $0.12, pro $0.23, ultra $0.33 (minimum $0.36 / $0.71 / $1.02), plus $0.06 for a script voiceover. Renders take 2–8 minutes: resume with cleus_get_result. Use a clear, front-facing portrait; never explicit, and only people who agreed to it.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","description":"Portrait (photo, generated image or Avatar shot) — face clearly visible."},"text":{"type":"string","description":"Script to speak (up to 2,500 characters; ~15 characters a second, 60 s max)."},"voice":{"type":"string","enum":["Sarah","Jessica","Laura","Bella","Matilda","Alice","Lily","Liam","Will","Eric","Chris","Brian","Roger","Adam","Bill","Callum","Harry","George","Daniel","Charlie","River"],"default":"Sarah","description":"Presenter voice for `text`."},"speed":{"type":"number","minimum":0.7,"maximum":1.2,"default":1},"vibe":{"type":"string","enum":["calm","natural","hyped"],"default":"natural"},"audio_url":{"type":"string","description":"Instead of text: your own speech audio (https, ≤60 s)."},"quality":{"type":"string","enum":["standard","pro","ultra"],"default":"pro"},"prompt":{"type":"string","description":"Optional delivery: expression, gestures, energy, setting (\"smiles, leans in, hand gestures\")."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["image_url"]}}}}}},"/videos/lip-sync":{"post":{"operationId":"postVideosLipSync","summary":"Re-sync a video’s lips to new audio (dubbing, new lines).","tags":["Video"],"description":"Re-sync the mouth movements in a video to a new audio track — dub a clip into another language, swap the line someone says, or sync a character to a voiceover. video_url: https MP4/MOV up to 60 s with a visible face; audio_url: the new speech (make it with cleus_generate_speech or cleus_clone_voice). $0.10 per second of video (minimum $0.12). Takes 1–5 minutes.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","description":"The video to re-sync (https, ≤60 s)."},"audio_url":{"type":"string","description":"The new speech audio."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["video_url","audio_url"]}}}}}},"/videos/enhance":{"post":{"operationId":"postVideosEnhance","summary":"Upscale to 4k, transparent background, or slow motion.","tags":["Video"],"description":"Improve a video (https, up to 60 s): upscale to 1080p, 2k or 4k ($0.02 / $0.03 / $0.06 per second); remove_background → transparent WebM with the audio kept ($0.10 per second); slow_motion → smoother 60 fps (slowdown 1) or real 2× / 4× slow motion ($0.06 per second × slowdown). Takes 1–5 minutes.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","description":"The video (https, ≤60 s)."},"action":{"type":"string","enum":["upscale","remove_background","slow_motion"]},"resolution":{"type":"string","enum":["1080p","2k","4k"],"default":"1080p","description":"For upscale."},"slowdown":{"type":"integer","enum":[1,2,4],"default":2,"description":"For slow_motion: 1 = smoother 60 fps, 2 or 4 = slow motion."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["video_url","action"]}}}}}},"/videos/analyze":{"post":{"operationId":"postVideosAnalyze","summary":"Shot-by-shot breakdown, cuts and a timed transcript of a video.","tags":["Video"],"description":"Watch a video (up to 3 minutes) and get back what is in it: a summary, a shot-by-shot breakdown with times (people, setting, action, camera, on-screen text), the cut points, the sound and style, and a full transcript with speakers and timestamps. Use it to understand a reference before remixing, write captions, find moments to cut, or dub (transcript → translate → cleus_clone_voice → cleus_lip_sync). $0.12 per video.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","description":"The video (public URL, upload or job id)."},"focus":{"type":"string","description":"Optional: what to look at closely, e.g. \"the hook in the first 3 seconds\" or \"every product shown\"."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["video_url"]}}}}}},"/videos/faceless":{"post":{"operationId":"postVideosFaceless","summary":"One idea → narrated, captioned faceless short videos, 1–4 parts (async).","tags":["Video"],"description":"Turn one idea into finished faceless short-form videos (TikTok/Reels/Shorts): Cleus writes the script, draws every scene in one look, adds a few moving shots, narrates it, scores it and burns in captions — 1 to 4 parts, 15 s to 5 min each, with a caption and hashtags per part. Formats: What if…, Scary story, Dark history, Did you know, Reddit story, Top 5, Motivation, Spicy story (18+); 18 looks from cinematic to pixel art. $2.61 per finished minute (seconds × parts). A part takes several minutes: the call returns an id — poll cleus_get_result.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"type":"string","description":"The idea, e.g. \"what if the moon disappeared\" or \"the night the Titanic sank\"."},"format":{"type":"string","enum":["what-if","scary","dark-history","did-you-know","reddit","top5","motivation","spicy"],"default":"did-you-know","description":"Storytelling format (sets the script shape, default voice and music): what-if (What if…: One impossible premise, consequences that escalate, a cliffhanger.); scary (Scary story: A first-person horror story with a slow build and a twist at the end.); dark-history (Dark history: True, little-known and grim moments from history, told like a documentary.); did-you-know (Did you know: Rapid-fire facts with numbers that make people rewatch.); reddit (Reddit story: A dramatic first-person story — AITA, revenge, family drama — with a verdict hook.); top5 (Top 5: A countdown from 5 to 1 — the best saved for last.); motivation (Motivation: A punchy mindset monologue — discipline, comebacks, stoic lines.); spicy (Spicy story: A steamy romance told in the second person — slow tension, tasteful visuals. 18+. 18+)."},"style":{"type":"string","enum":["cinematic","toy-3d","pixar","clay","low-poly","voxel","anime","noir","comic","ink","watercolor","woodblock","pixel","cartoon-30s","flat","blueprint","archive","horror"],"description":"Visual look; defaults to the format's own: cinematic (Film stills, real light); toy-3d (Tilt-shift miniature 3D); pixar (Feature-film animation); clay (Matte clay, soft pastels); low-poly (Faceted, bright and clean); voxel (Blocky cube worlds); anime (Painted anime dusk); noir (Black ink, one red accent); comic (Halftone, bold outlines); ink (Sumi ink, gold leaf); watercolor (Soft washes on paper); woodblock (Japanese print, indigo sea); pixel (16-bit retro game); cartoon-30s (Rubber-hose, aged paper); flat (Bold shapes, explainer look); blueprint (Wireframe on navy); archive (Grainy, sepia, historical); horror (Dark, grainy, unsettling)."},"seconds":{"type":"integer","enum":[15,30,45,60,90,120,180,300],"default":60,"description":"Length of each part."},"parts":{"type":"integer","minimum":1,"maximum":4,"default":1,"description":"Episodes in the series (part 2 continues part 1)."},"aspect_ratio":{"type":"string","enum":["9:16","16:9","1:1"],"default":"9:16"},"voice":{"type":"string","enum":["Brian","Daniel","George","Callum","Bill","Adam","Liam","Chris","Eric","Jessica","Laura","Sarah","Lily","Matilda","River"],"description":"Narrator. Default: the format's. Brian (Deep, trailer), Daniel (British broadcaster), George (British storyteller), Callum (Husky, eerie), Bill (Old, wise), Adam (Firm, intense), Liam (Young creator), Chris (Casual), Eric (Smooth), Jessica (Playful), Laura (Social media), Sarah (Confident), Lily (Velvety), Matilda (Upbeat), River (Calm, neutral)."},"language":{"type":"string","enum":["es","pt","fr","de","it","hi","ja","ko","tr","pl","id"],"description":"Narration language. Default English. es = Spanish, pt = Portuguese, fr = French, de = German, it = Italian, hi = Hindi, ja = Japanese, ko = Korean, tr = Turkish, pl = Polish, id = Indonesian."},"adult":{"type":"boolean","description":"Required true for the 18+ \"spicy\" format (adult characters only)."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["topic"]}}}}}},"/videos/remix":{"post":{"operationId":"postVideosRemix","summary":"Clone a reference video’s format, swap someone in, or restyle it (async).","tags":["Video"],"description":"Clone a viral or reference video (up to 3 minutes) into your own version with the Imagine Agent. mode \"recreate\" (default): same format, hook, pacing, shots and captions with your topic, product or people; \"swap\": the same clip with your person/character/product from the photos; \"restyle\": same motion in a new look or setting. Pass the video as an MP4 URL (not a TikTok/Instagram page link — download or upload it first), your brief in instructions and any photos in image_urls. Pays for what it generates, capped by budget_usd ($1, $3, $6, $12, $25; default $3). Takes 5–30 minutes: resume with cleus_get_result; continue the project with cleus_imagine_agent { thread_id }. Only remix videos you have the rights to.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","description":"The reference video (MP4 URL, upload or job id)."},"instructions":{"type":"string","description":"What to change, e.g. \"about my oat-milk brand, with the product shots from image 1\" or \"anime style\"."},"mode":{"type":"string","enum":["recreate","swap","restyle"],"default":"recreate"},"image_urls":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Your people, characters or products."},"budget_usd":{"type":"number","enum":[1,3,6,12,25],"default":3},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["video_url"]}}}}}},"/videos/dub":{"post":{"operationId":"postVideosDub","summary":"Dub a video into another language in the speakers’ own voices.","tags":["Video"],"description":"Translate the speech in a video (or audio) into another language in the original speakers' own voices, timing kept — one call, speakers detected automatically. $1.2 per started minute. For lips that match the new language too, run cleus_lip_sync on the result. Only dub content you have the rights to.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","description":"The video (public URL, upload or job id). Or pass audio_url instead."},"audio_url":{"type":"string","description":"Dub an audio file instead of a video."},"target_language":{"type":"string","description":"Language to dub into: a name (\"Spanish\") or ISO code (\"es\")."},"source_language":{"type":"string","description":"Optional: the original language (auto-detected)."},"speakers":{"type":"integer","minimum":1,"maximum":9,"description":"Optional: how many people speak (auto-detected)."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["target_language"]}}}}}},"/videos/reframe":{"post":{"operationId":"postVideosReframe","summary":"Change a video’s aspect ratio by generating the missing edges.","tags":["Video"],"description":"Change a video's shape — e.g. a 16:9 clip into 9:16 for TikTok/Reels, or vertical into widescreen — by generating the missing picture around it (nothing is cropped away). Up to 5 minutes. $0.1/s at 480p or $0.16/s at 768p (long videos are done in overlapping windows, billed a little over their length).","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","description":"The video (public URL, upload or job id)."},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1","4:3","3:4","21:9","9:21"],"default":"9:16"},"resolution":{"type":"string","enum":["480p","768p"],"default":"768p"},"prompt":{"type":"string","description":"Optional: what the new surroundings should show."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["video_url"]}}}}}},"/videos/sound":{"post":{"operationId":"postVideosSound","summary":"Synced sound effects and ambience for a video.","tags":["Video"],"description":"Give a silent (or under-designed) video a soundtrack that matches what happens on screen — footsteps, impacts, engines, ambience, music — synced to the picture. Speech already in the video is kept unless keep_speech is false. Covers the whole video (up to 10 minutes) unless duration is set. $0.02 per second.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","description":"The video (public URL, upload or job id)."},"prompt":{"type":"string","description":"Optional: sounds the picture doesn't show, or the mood (\"tense synth score\")."},"avoid":{"type":"string","description":"Optional: sounds to keep out, comma-separated."},"keep_speech":{"type":"boolean","default":true},"duration":{"type":"number","minimum":1,"maximum":600,"description":"Seconds of sound (default: the whole video)."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["video_url"]}}}}}},"/imagine-agent":{"post":{"operationId":"postImagineAgent","summary":"Imagine Agent: plans, generates, reviews and edits whole productions (async).","tags":["Video"],"description":"Hand a whole creative project to the Cleus Imagine Agent: a director that plans it, writes the script, generates images, video clips, voiceover and music across all Cleus models, reviews every take with vision, redoes weak ones and cuts the final edit. Great for ads, music videos, short films, explainers, UGC, trailers, remakes of a reference video (video_url) and \"put me in this video\" swaps. Continue or answer a project by passing its thread_id with your next message (when status is \"waiting\", reply with one of its options). budget_usd caps the spend of one request ($1, $3, $6, $12, $25; default $3); answering its \"Raise limit to $X\" option raises it to that tier. Projects take 3–30 minutes: resume with cleus_get_result. Up to 3 projects can work at once (one message at a time per project); stop one with stop: true. Projects also appear in the user's Imagine → Agent tab.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"What to make (or your answer to its question)."},"thread_id":{"type":"string","description":"Continue this project."},"image_urls":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Reference images: products, people, characters, styles."},"video_url":{"type":"string","description":"A reference video to remake in your own version or to swap someone into."},"generation_ids":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Earlier Cleus results to use (ids from cleus_list_generations)."},"budget_usd":{"type":"number","enum":[1,3,6,12,25],"default":3},"image_model":{"type":"string","enum":["auto","uncensored","pro","quality","nano-banana-2.1","gpt-image-2.5","grok-imagine"],"default":"uncensored"},"video_model":{"type":"string","enum":["auto","seedance-uncensored","quality","uncensored","kling","seedance","grok-imagine"],"default":"seedance-uncensored"},"ask_to_pick":{"type":"boolean","default":false,"description":"Stop for the user twice: to OK the script before anything is spent, and to pick which take to animate before making videos."},"stop":{"type":"boolean","description":"Stop the running request in thread_id."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}}}}}}}},"/audio/speech":{"post":{"operationId":"postAudioSpeech","summary":"Text to speech with preset voices.","tags":["Audio"],"description":"Turn text into natural speech (MP3) with a preset voice: Aiden (Male, sunny American English), Ryan (Male, dynamic and punchy), Eric (Male, lively, slightly husky), Dylan (Male, youthful and clear), Uncle_Fu (Male, seasoned, low and mellow), Vivian (Female, bright with an edge), Serena (Female, warm and gentle), Ono_Anna (Female, playful, native Japanese), Sohee (Female, warm, native Korean). Languages: auto, English, Chinese, Spanish, French, German, Italian, Japanese, Korean, Portuguese, Russian. Optional style instruction (\"whispering, slow, mysterious\"). Up to 5,000 characters per call — split longer scripts. $0.08 per 1,000 characters. To speak in a specific person's voice use cleus_clone_voice.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"What to say."},"voice":{"type":"string","enum":["Aiden","Ryan","Eric","Dylan","Uncle_Fu","Vivian","Serena","Ono_Anna","Sohee"],"default":"Aiden"},"language":{"type":"string","enum":["auto","English","Chinese","Spanish","French","German","Italian","Japanese","Korean","Portuguese","Russian"],"default":"auto"},"style":{"type":"string","description":"Optional delivery instruction: emotion, pace, tone."},"engine":{"type":"string","enum":["standard","studio"],"default":"standard","description":"\"studio\" = 21 premium studio voices (Sarah, Jessica, Laura, Bella, Matilda, Alice, Lily, Liam, Will, Eric, Chris, Brian, Roger, Adam, Bill, Callum, Harry, George, Daniel, Charlie, River), most natural for voiceovers, up to 2,500 characters, $0.06 per clip; pass studio_voice and optional speed / vibe."},"studio_voice":{"type":"string","enum":["Sarah","Jessica","Laura","Bella","Matilda","Alice","Lily","Liam","Will","Eric","Chris","Brian","Roger","Adam","Bill","Callum","Harry","George","Daniel","Charlie","River"],"description":"Sarah: Female, mature, reassuring (American); Jessica: Female, playful, bright (American); Laura: Female, enthusiastic, quirky (American); Bella: Female, professional, warm (American); Matilda: Female, knowledgeable, upbeat (American); Alice: Female, clear educator (British); Lily: Female, velvety actress (British); Liam: Male, energetic creator (American); Will: Male, relaxed optimist (American); Eric: Male, smooth, trustworthy (American); Chris: Male, charming, down-to-earth (American); Brian: Male, deep, comforting (American); Roger: Male, laid-back, resonant (American); Adam: Male, dominant, firm (American); Bill: Male, wise, mature (American); Callum: Male, husky trickster (American); Harry: Male, fierce warrior (American); George: Male, warm storyteller (British); Daniel: Male, steady broadcaster (British); Charlie: Male, deep, energetic (Australian); River: Neutral, relaxed (American)"},"speed":{"type":"number","minimum":0.7,"maximum":1.2,"default":1,"description":"Studio voices: speaking speed."},"vibe":{"type":"string","enum":["calm","natural","hyped"],"default":"natural","description":"Studio voices: delivery energy."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["text"]}}}}}},"/audio/voice-clone":{"post":{"operationId":"postAudioVoiceClone","summary":"Speak text in a voice from a short sample.","tags":["Audio"],"description":"Speak any text in the voice from a short sample: voice_sample_url is an audio or video clip (5–30 s of one clear speaker; only the first 30 s is used), or saved_voice_id is a voice the user saved in Cleus Imagine (see cleus_list_voices). Languages: auto, English, Arabic, Chinese, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish (auto-detected by default). Every piece is checked by speech recognition and re-spoken if it comes out wrong. Up to 5,000 characters per call. $0.08 per 1,000 characters. Only clone voices you have the right to use.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"What to say."},"voice_sample_url":{"type":"string","description":"Public URL of the voice sample (mp3, wav, m4a, webm or a video)."},"saved_voice_id":{"type":"string","description":"Id of a saved voice from cleus_list_voices."},"language":{"type":"string","enum":["auto","English","Arabic","Chinese","Danish","Dutch","Finnish","French","German","Greek","Hebrew","Hindi","Italian","Japanese","Korean","Malay","Norwegian","Polish","Portuguese","Russian","Spanish","Swahili","Swedish","Turkish"],"default":"auto"},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["text"]}}}}}},"/audio/music":{"post":{"operationId":"postAudioMusic","summary":"Compose a full song with vocals and cover art, or an instrumental.","tags":["Audio"],"description":"Compose a full song (MP3, usually 1–3 minutes) with vocals, plus cover art. style = genre, mood, instruments, vocal type (\"dreamy synth-pop, female vocals, 110 bpm\"). lyrics = your own lyrics with [Verse]/[Chorus]/[Bridge] tags, or leave empty and Cleus writes them; instrumental: true for no vocals. $0.12 per song. Takes 1–3 minutes.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"style":{"type":"string","description":"Genre, mood, instruments, vocals, tempo (≤300 characters)."},"lyrics":{"type":"string","description":"Optional lyrics with section tags (≤3,000 characters). Language follows the lyrics."},"instrumental":{"type":"boolean","default":false},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["style"]}}}}}},"/audio/sound-effects":{"post":{"operationId":"postAudioSoundEffects","summary":"A sound effect or ambience from a description, up to 22 s.","tags":["Audio"],"description":"Make a sound effect or short ambience from a description — \"glass shattering on concrete\", \"spaceship door hiss\", \"rain on a tin roof, 20 s\" — 0.5 to 22 seconds, MP3. $0.04 each. For music use cleus_generate_music.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"The sound, as specific as possible (source, material, distance, mood)."},"duration":{"type":"number","minimum":0.5,"maximum":22,"default":4,"description":"Seconds."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["prompt"]}}}}}},"/audio/voice-change":{"post":{"operationId":"postAudioVoiceChange","summary":"Re-voice speech in another voice, same words and delivery (audio or video).","tags":["Audio"],"description":"Re-voice speech in another voice while keeping the exact words, timing and emotion (speech-to-speech): an audio clip, or a video — then you also get the video back with the new voice. Voices: Sarah, Jessica, Laura, Bella, Matilda, Alice, Lily, Liam, Will, Eric, Chris, Brian, Roger, Adam, Bill, Callum, Harry, George, Daniel, Charlie, River. Up to 5 minutes. $0.06 per started minute. Background music in the source is not kept; for new words in a cloned voice use cleus_clone_voice. Only re-voice recordings you have the rights to.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"media_url":{"type":"string","description":"Audio or video with the speech (public URL, upload or job id)."},"voice":{"type":"string","enum":["Sarah","Jessica","Laura","Bella","Matilda","Alice","Lily","Liam","Will","Eric","Chris","Brian","Roger","Adam","Bill","Callum","Harry","George","Daniel","Charlie","River"],"description":"Sarah: Female, mature, reassuring (American); Jessica: Female, playful, bright (American); Laura: Female, enthusiastic, quirky (American); Bella: Female, professional, warm (American); Matilda: Female, knowledgeable, upbeat (American); Alice: Female, clear educator (British); Lily: Female, velvety actress (British); Liam: Male, energetic creator (American); Will: Male, relaxed optimist (American); Eric: Male, smooth, trustworthy (American); Chris: Male, charming, down-to-earth (American); Brian: Male, deep, comforting (American); Roger: Male, laid-back, resonant (American); Adam: Male, dominant, firm (American); Bill: Male, wise, mature (American); Callum: Male, husky trickster (American); Harry: Male, fierce warrior (American); George: Male, warm storyteller (British); Daniel: Male, steady broadcaster (British); Charlie: Male, deep, energetic (Australian); River: Neutral, relaxed (American)"},"remove_background_noise":{"type":"boolean","default":false},"media_seconds":{"type":"number","description":"Length in seconds, if known."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["media_url","voice"]}}}}}},"/audio/voices":{"get":{"operationId":"getAudioVoices","summary":"Preset voices and your saved voice clones.","tags":["Audio"],"description":"List the preset speech voices and the user's saved voices (cloned in Cleus Imagine) with their ids. Free.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/characters":{"get":{"operationId":"getCharacters","summary":"Search public characters (or ?mine=true for yours).","tags":["Characters"],"description":"Search Cleus characters — thousands of community-made roleplay characters (anime, fantasy, romance, games, companions, helpers) — or list the user’s own. Returns ids, names, descriptions and avatars; chat with one using cleus_character_chat. Free.","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string","description":"Words to match in the name or description, e.g. \"vampire\", \"detective\", \"Gojo\"."}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["popular","trending","new"],"default":"popular"}},{"name":"mine","in":"query","required":false,"schema":{"type":"boolean","default":false,"description":"List the user’s own characters instead (including private ones)."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"postCharacters","summary":"Create a character.","tags":["Characters"],"description":"Create a Cleus roleplay character the user can chat with here (cleus_character_chat) and at cleus.ai: name, look and backstory (about), personality, scenario, greeting and example messages. Without avatar_url Cleus draws an avatar. Private by default; public: true submits it for review to appear in Discover. Characters must be adults (18+). Photos of real people who aren’t public figures stay private. Free.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Up to 20 characters."},"gender":{"type":"string","enum":["Female","Male","Non-binary","Other"]},"age":{"type":"integer","minimum":18,"default":25},"about":{"type":"string","description":"Who they are: looks, backstory, world, relationships (≤190 words)."},"personality":{"type":"string","description":"Traits, voice, quirks, how they talk (≤100 words)."},"details":{"type":"string","description":"Optional extra details: likes, dislikes, secrets (≤100 words)."},"scenario":{"type":"string","description":"Optional starting situation for chats (≤600 characters). Supports {{user}} and {{char}}."},"greeting":{"type":"string","description":"Optional first message (≤800 characters). Written for you if empty."},"example_messages":{"type":"array","maxItems":5,"description":"Optional sample exchanges that teach their voice.","items":{"type":"object","properties":{"user":{"type":"string"},"character":{"type":"string"}},"required":["user","character"]}},"avatar_url":{"type":"string","description":"Optional avatar image URL. Omit to have one drawn."},"public":{"type":"boolean","default":false,"description":"Submit for Discover (reviewed first). Private characters are only for this user."},"nsfw":{"type":"boolean","default":false,"description":"Adult character: never listed publicly."}},"required":["name","gender","about","personality"]}}}}}},"/characters/{id}":{"get":{"operationId":"getCharactersId","summary":"Character card, optionally with ?history=N recent messages.","tags":["Characters"],"description":"Get a Cleus character’s full card (about, personality, scenario, greeting, example messages, avatar, link) and optionally the latest messages of the user’s chat with them. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"character id"},{"name":"history","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":60,"default":0,"description":"Include this many recent chat messages."}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/characters/{id}/messages":{"post":{"operationId":"postCharactersIdMessages","summary":"Send a message and get the in-character reply.","tags":["Characters"],"description":"Send a message to a Cleus character and get their in-character reply (uncensored roleplay that remembers the whole conversation, with bond levels and long-term memory). This is the user’s own chat with that character, shared with the Cleus app. The first message in a new chat also returns the character’s greeting. Use persona to say who the user is in the story. Text only. $0.02 per reply. Find ids with cleus_character_search or make one with cleus_character_create.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"character id"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"What the user says or does (actions in *asterisks*)."},"persona":{"type":"object","description":"Optional: who the user plays in this chat (saved for this character).","properties":{"name":{"type":"string"},"about":{"type":"string"},"gender":{"type":"string","enum":["woman","man","nonbinary"],"description":"So the character uses the right pronouns."}}},"style":{"type":"string","enum":["texting","story"],"description":"Optional: \"texting\" (short texts, default) or \"story\" (long narrated replies). Saved for this chat."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["message"]}}}}}},"/stories":{"get":{"operationId":"getStories","summary":"List your stories.","tags":["Stories"],"description":"List the user's Cleus stories (newest first) with their ids — including ones started on cleus.ai.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"postStories","summary":"Start a story and write chapter 1.","tags":["Stories"],"description":"Start a new story in Cleus Story mode (uncensored long-form fiction with persistent story memory) and write chapter 1. The story is saved to the user's Cleus account and opens in Story Studio at cleus.ai/story (export to EPUB/PDF/DOCX there). Chapters take 30–90s; if the result is \"processing\", resume with cleus_get_result. Billed from the Cleus balance: $6 / 1M tokens of story memory + output (≈$0.03–$0.15 a chapter); illustrations $0.09 each.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Story title."},"plot":{"type":"string","description":"Premise / plot description: setting, conflict, where it should go, any style notes."},"genres":{"type":"string","description":"Up to 4 comma-separated genres, e.g. \"Fantasy, Romance\"."},"characters":{"type":"array","description":"Main characters.","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","description":"Looks, personality, role, backstory."}},"required":["name"]}},"writing_style":{"type":"string","enum":["default","novel","screenplay","dialogue","comic","sensual","literary","noir","sliceOfLife","firstPerson","erotic"],"default":"novel"},"narrator_tone":{"type":"string","enum":["serious","playful","sarcastic","flirty"],"default":"serious"},"chapter_words":{"type":"integer","minimum":500,"maximum":5000,"default":1500,"description":"Target length of each chapter."},"explicit":{"type":"boolean","default":false,"description":"Adult (18+) explicit wording — name things plainly instead of using euphemisms."},"illustrate":{"type":"boolean","default":false,"description":"Draw a cover-style illustration for every chapter ($0.09 each, consistent art style)."},"scene_images":{"type":"integer","minimum":0,"maximum":3,"default":0,"description":"Extra in-story scene illustrations per chapter ($0.09 each)."},"model":{"type":"string","enum":["cleus-fast","cleus-fast-v2","cleus-fast-v3","cleus-smartest-1","cleus-smartest-2","cleus-smartest-3"],"default":"cleus-smartest-1","description":"cleus-smartest-1 plans before writing (best continuity); cleus-fast is quicker."},"first_instruction":{"type":"string","description":"Optional direction for chapter 1 (defaults to \"Write the first chapter\")."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["title","plot"]}}}}}},"/stories/{id}":{"get":{"operationId":"getStoriesId","summary":"Premise, cast, chapter list and chapter text (?chapter=N, 0 = all).","tags":["Stories"],"description":"Read a Cleus story: its premise, cast, the chapter list, and the full text of one chapter (the latest by default, or chapter: N, or chapter: 0 for all chapters), with illustration URLs.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"story id"},{"name":"chapter","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Chapter number; 0 = every chapter. Defaults to the latest."}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"patchStoriesId","summary":"Change settings for the chapters ahead.","tags":["Stories"],"description":"Change a Cleus story's settings for the chapters still to come: premise, cast, genres, writing style, narrator tone, chapter length, explicit 18+ wording, illustrations or default model. Existing chapters are kept. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"story id"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"plot":{"type":"string","description":"New premise / plot notes (replaces the old one)."},"genres":{"type":"string"},"characters":{"type":"array","description":"Full cast list (replaces the old one). Read the story first to keep existing characters.","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name"]}},"writing_style":{"type":"string","enum":["default","novel","screenplay","dialogue","comic","sensual","literary","noir","sliceOfLife","firstPerson","erotic"]},"narrator_tone":{"type":"string","enum":["serious","playful","sarcastic","flirty"]},"chapter_words":{"type":"integer","minimum":500,"maximum":5000},"explicit":{"type":"boolean"},"illustrate":{"type":"boolean"},"scene_images":{"type":"integer","minimum":0,"maximum":3},"model":{"type":"string","enum":["cleus-fast","cleus-fast-v2","cleus-fast-v3","cleus-smartest-1","cleus-smartest-2","cleus-smartest-3"]}}}}}}}},"/stories/{id}/chapters":{"post":{"operationId":"postStoriesIdChapters","summary":"Write the next chapter, optionally steered.","tags":["Stories"],"description":"Write the next chapter of a Cleus story. Optionally steer it (\"Mara finally confronts her brother\", \"make it darker\", \"rewrite in first person from now on\"). Cleus keeps characters, facts and voice consistent across chapters. If the result is \"processing\", resume with cleus_get_result.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"story id"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"direction":{"type":"string","description":"Optional direction for what should happen next."},"model":{"type":"string","enum":["cleus-fast","cleus-fast-v2","cleus-fast-v3","cleus-smartest-1","cleus-smartest-2","cleus-smartest-3"],"description":"Optional model override for this chapter."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}}}}}}}},"/stories/{id}/chapters/{n}":{"patch":{"operationId":"patchStoriesIdChaptersN","summary":"Rename, rewrite, delete or move a chapter (action: rename | edit | delete | move).","tags":["Stories"],"description":"Rename, rewrite, delete or move one chapter of a Cleus story (numbers as in cleus_story_read and Story Studio). \"edit\" replaces the chapter text (the old text is kept in its version history at cleus.ai/story). After edit, delete or move, the story memory is rebuilt so later chapters follow the new book. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"story id"},{"name":"n","in":"path","required":true,"schema":{"type":"string"},"description":"chapter"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["rename","edit","delete","move"]},"title":{"type":"string","description":"rename / edit: the new chapter title (\"\" clears it)."},"text":{"type":"string","description":"edit: the full new chapter text (Markdown, without the chapter heading)."},"to":{"type":"integer","minimum":1,"description":"move: the chapter number it should become."}},"required":["action"]}}}}}},"/files":{"post":{"operationId":"postFiles","summary":"Upload a file (multipart, base64 or URL) or get a signed upload URL.","tags":["Files & jobs"],"description":"Host an image, video or audio file on Cleus so other Cleus tools can use it (reference images, start frames, videos to edit or swap into, voice samples, music). Three ways: (1) `url` — import a public http(s) URL; (2) `base64` — a data URL or base64 string up to 3 MB; (3) `filename` only — returns a one-hour upload URL and a ready curl command for big local files (videos): run the command, then use the returned file_url. Every Cleus tool that takes an image/video/audio URL also accepts public URLs directly, so only upload local files or URLs Cleus cannot reach. Free.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Public http(s) URL of a file to import."},"base64":{"type":"string","description":"File contents as a data URL (data:image/png;base64,…) or bare base64 (≤3 MB)."},"filename":{"type":"string","description":"Local file name, e.g. \"clip.mp4\". Used for the file type; with no url/base64 you get an upload URL + curl command."},"content_type":{"type":"string","description":"MIME type override, e.g. \"video/mp4\"."}}}}}}}},"/generations":{"get":{"operationId":"getGenerations","summary":"Your recent images, videos and audio.","tags":["Files & jobs"],"description":"List the user's recent Cleus creations (images, videos, audio) — including ones made on cleus.ai — with their URLs, prompts and job ids, newest first. Use it to reuse an earlier result (e.g. animate an image made on the web) or find a job id. Free.","parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["all","image","video","audio"],"default":"all"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":15}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/jobs/{id}":{"get":{"operationId":"getJobsId","summary":"Status and result of any job (videos, songs, chapters, replies…).","tags":["Files & jobs"],"description":"Wait for (up to ~45 s per call) and return Cleus jobs that came back as \"processing\": videos, images, audio, talking videos, video tools, faceless series, Avatars, 3D models, video analyses, Imagine Agent projects, long replies, story chapters and character replies. Pass one `id`, or up to 12 `ids` (e.g. from cleus_generate_batch) to wait for them together. Call again until every job is \"completed\" or failed. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"id"},{"name":"ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":12,"description":"Several job ids to wait for together."}},{"name":"wait","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/tools":{"get":{"operationId":"getTools","summary":"Every tool with its JSON schema (same as the MCP server).","tags":["Files & jobs"],"parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/tools/{name}":{"post":{"operationId":"postToolsName","summary":"Call any tool by name with its JSON arguments.","tags":["Files & jobs"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"Tool name from GET /v1/tools, e.g. cleus_generate_video."}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"The tool's arguments."}}}}}},"/models":{"get":{"operationId":"getModels","summary":"All chat, image, video and audio models.","tags":["Account"],"description":"Explore Cleus models (image, video, audio, 3D): durations, resolutions, aspect ratios, sound and end frames. action \"recommend\" + goal (\"logo with the word Orbit\", \"8 s cinematic drone shot from my photo\") → the best models for it with reasons; \"get\" + model_id → one model in detail; \"search\" + query; \"list\" (default) → every model. Every answer includes prices (list also covers every tool). Use it before generating when unsure which model fits. Free.","parameters":[{"name":"action","in":"query","required":false,"schema":{"type":"string","enum":["list","search","get","recommend"],"default":"list"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["image","video","audio","3d"],"description":"Only this kind of output."}},{"name":"model_id","in":"query","required":false,"schema":{"type":"string","description":"For \"get\": a model id such as \"kling\" or \"gpt-image-2.5\"."}},{"name":"query","in":"query","required":false,"schema":{"type":"string","description":"For \"search\": words to match in names and descriptions."}},{"name":"goal","in":"query","required":false,"schema":{"type":"string","description":"For \"recommend\": what the user wants to make, in plain words."}},{"name":"input","in":"query","required":false,"schema":{"type":"string","enum":["text","image"],"description":"For \"recommend\": \"image\" when starting from a reference image or photo."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":3,"description":"For \"recommend\": how many picks."}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/models/search":{"get":{"operationId":"getModelsSearch","summary":"Search 1,400+ more models (?query=…), or ?model=<id> for its inputs and price.","tags":["Account"],"description":"Search 1,400+ more generation models beyond the built-in ones — the newest image, video, music, speech, sound, 3D, upscaling, cutout, stem-splitting and transcription models (FLUX 3, Ideogram 4.5, Recraft 4.1, Krea 3, MiniMax H3 Max, Vidu Q4, ElevenLabs Music, Lyria, Eleven v4 TTS, Meshy 7.1…). No arguments: the featured list. query (+ optional category) to search; model to get its exact inputs and price. Run one with cleus_run_model. Prefer the built-in tools when they fit. Free.","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string","description":"What you need, e.g. \"logo vector\", \"lip sync\", \"anime video\", \"song with vocals\"."}},{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["text-to-image","image-to-image","text-to-video","image-to-video","video-to-video","text-to-audio","text-to-speech","audio-to-audio","speech-to-speech","video-to-audio","audio-to-video","image-to-3d","text-to-3d","3d-to-3d","speech-to-text","vision","video-to-text","image-to-text","audio-to-text"]}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["image","video","audio","3d"],"description":"Featured list only: just this kind."}},{"name":"model","in":"query","required":false,"schema":{"type":"string","description":"A model id: returns its exact inputs. The answer includes its price."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30,"default":15}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/models/run":{"post":{"operationId":"postModelsRun","summary":"Run any of those models with its own inputs, priced up front.","tags":["Account"],"description":"Run any model from cleus_find_models with its own inputs (input object, field names as listed by cleus_find_models { model }). The exact price is worked out first from the inputs (get_cost: true returns it without running); runs over about $15 are refused. File inputs take public URLs, Cleus job ids or @asset handles. Results (images, videos, audio, 3D, SVG, text) are kept on Cleus and returned as URLs; long runs return an id for cleus_get_result.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Model id, e.g. \"ideogram/v4.5\"."},"input":{"type":"object","description":"The model's inputs, e.g. { \"prompt\": \"…\", \"quality\": \"high\" }."},"wait":{"type":"integer","minimum":0,"maximum":240,"description":"Seconds to wait for the result (default 45; 0 = return a job id at once)."}},"required":["model","input"]}}}}}},"/balance":{"get":{"operationId":"getBalance","summary":"Your remaining USD balance.","tags":["Account"],"description":"Show the remaining USD balance on the user's Cleus account. Free.","parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/transactions":{"get":{"operationId":"getTransactions","summary":"Balance, recent top-ups and spend per day.","tags":["Account"],"description":"The user's Cleus money: current USD balance, recent top-ups, and net spend per day (in-app and API) for the last N days. Single charges aren't itemised. Free.","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30,"default":7}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/assets":{"get":{"operationId":"getAssets","summary":"Your @tag asset library (POST with action \"save\" to add one).","tags":["Files & jobs"],"description":"The user's Cleus asset library (cleus.ai/assets): saved characters, Avatars, locations, props and images, each with an @handle. action \"list\" shows them; action \"save\" adds an image (URL or job id) under a handle so it can be reused later. Any *_url argument of any Cleus tool also accepts \"@handle\" — e.g. image_url: \"@nova\" — so saved characters and products stay consistent across generations. Free.","parameters":[{"name":"action","in":"query","required":false,"schema":{"type":"string","enum":["list","save"],"default":"list"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["image","character","avatar","location","prop"],"description":"list: only this kind. save: what the image is (default image)."}},{"name":"image_url","in":"query","required":false,"schema":{"type":"string","description":"save: the image to keep (public URL, upload or job id)."}},{"name":"name","in":"query","required":false,"schema":{"type":"string","description":"save: a name, e.g. \"Nova\" — the handle is made from it unless you pass handle."}},{"name":"handle","in":"query","required":false,"schema":{"type":"string","description":"save: the @handle to use (a–z, 0–9, _)."}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/security/analyze":{"post":{"operationId":"postSecurityAnalyze","summary":"Offline and passive security checks: JWT, hashes, SPF/DKIM/DMARC, CVEs, TLS, recon.","tags":["Security"],"parameters":[],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}},"/chat/completions":{"post":{"operationId":"createChatCompletion","summary":"OpenAI-compatible chat completions (streaming supported).","tags":["Text"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","enum":["cleus-agent","cleus-fast","cleus-fast-v2","cleus-fast-v3","cleus-smartest-1","cleus-smartest-2","cleus-smartest-3","cleus-coding-3","deepseek-v4.1-flash-abliterated","glm-5.3-abliterated","glm-5.3-flash-abliterated","qwen-3.8-27b-abliterated","kimi-k3.1-pro-abliterated","hy4-abliterated"]},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}}},"stream":{"type":"boolean"}}}}}},"responses":{"200":{"description":"chat.completion (or an SSE stream)"},"202":{"$ref":"#/components/responses/Job"},"4XX":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your clsk_live_… key from cleus.ai/developers"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":["string","null"]}}}}}}}},"Job":{"description":"Still working — poll GET /v1/jobs/{id}","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"job"},"status":{"const":"processing"},"poll_url":{"type":"string"}}}}}}}}}