{"openapi":"3.1.0","info":{"title":"Icarus API","version":"1.0.0","description":"Make your marketing from your own code: pictures, videos and audio with your saved products and characters, paid from the same balance as the app.\n\n- **Get a key:** make one in [Settings, API and MCP](https://withicarus.com/dashboard/settings?tab=api-keys). New to Icarus? Sign up free, then make a key.\n- **Address:** `https://myth.withicarus.com/v1`\n- **Sign in:** send the key as `Authorization: Bearer <key>`. A key in the address is refused.\n- **Limits:** 300 calls a minute per key and 30 paid renders a minute per workspace, shared with MCP. Over the limit you get 429 and `Retry-After`.\n- **Retries:** send an `Idempotency-Key` (8 to 128 characters) with every paid call. The same key and request returns the first result for 24 hours and charges once.\n- **Renders:** a paid call answers 202 with the shot's `generationId`. Check `GET /v1/generations/{generationId}` every 5 seconds until it is `completed` or `failed`. Files stay at their links.\n- **Price first:** add `getCost: true` to any paid call to see its price. Nothing is made.\n\n## Errors\n\nEvery error is `application/problem+json` with `status`, `detail` (a sentence you can show), `code` and `requestId`: 400 bad input, 401 no or wrong key, 402 balance too low, 403 the key can't do that, 404 not found, 409 the same request is still running, 422 an `Idempotency-Key` reused for a different request, 429 over the limit."},"servers":[{"url":"https://myth.withicarus.com"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A workspace API key from Settings, API and MCP."}},"schemas":{"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string"}}}}},"paths":{"/v1/me":{"get":{"operationId":"whoami","summary":"Who am I","description":"Get the workspace this key works in, the key's owner, its scopes and the credit balance. Use it when they ask which workspace they are in, who is signed in or how many credits they have left. Returns workspace (id, name, creditBalance), user (id, email, name), scopes, and instructions: the person's standing instructions for Icarus, to follow in every reply (\"\" when none, and outside Icarus's own chats). For saved products or models, call list_products or list_characters instead.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/models":{"get":{"operationId":"list_models","summary":"List available models","description":"List the image and video models this workspace can use, what each is best for, and the settings each takes: sizes, frame shapes, lengths, resolutions and how many reference images, clips and sound files it reads. Use it when they ask which models there are, which one fits a job, or what sizes, lengths or settings one takes. Returns { image, video, audio, videoDefault, editModels, matchedNeeds }: image[].id goes in model, video[].slug in videoModel, audio[].slug in an audio tool's model, and editModels in edit_image's editModel. for ranks each list best first with a score and why; model returns one row; type and needs narrow; type audio lists the voice models for create_speech, change_voice and translate_video. Call it before naming a model or sending a setting only some models take; an ordinary image needs no lookup. A model that is not listed is refused, never swapped. On motion control the duration range is the driving clip's length (drivingClipSeconds).","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["image","video","audio"],"description":"image, video, or audio for the voice models. Omit for image and video models."}},{"name":"needs","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["sound","reference-photos","reference-clip","edit-a-clip","extend-a-clip","last-frame","4k","edit-a-photo","one-look-across-a-set"]},"maxItems":9,"description":"Only models that can do all of these. sound: Renders sound with the clip. reference-photos: Reads reference photos, so a saved product or character can be pinned. reference-clip: Reads a clip you supply, to follow its look or its movement. edit-a-clip: Changes a clip you already have. extend-a-clip: Carries an existing clip on for longer. last-frame: Takes a closing frame as well as an opening one. 4k: Renders at 4K, for print or a large display. edit-a-photo: Changes a picture you already have, rather than making a new one. one-look-across-a-set: Pins a look from reference pictures and reuses it across a whole set, so every asset matches."}},{"name":"for","in":"query","required":false,"schema":{"type":"string","maxLength":300,"description":"The job in plain words. Ranks each list best first and adds the needs the words imply."}},{"name":"model","in":"query","required":false,"schema":{"type":"string","maxLength":100,"description":"One model's id or slug. Returns only that model's row."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/search":{"get":{"operationId":"search_workspace","summary":"Search the workspace","description":"Search the workspace's own products, characters, studio blocks and shot prompts for one word at once. Use it when they ask to find something by name (\"find the Dune one\", \"where is the summer stuff\") and you don't know which kind holds it. Each call reads one page of each kind and keeps the matches, so a page can be empty while more remain. Returns products, characters, studios (blocks with category), shots, and nextCursors per kind; pass one nextCursors value as cursor to read deeper into that kind (the others come back empty). Does not cover folders or assets; when you know the kind, list_products or list_characters is quicker.","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"A name, topic or word."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128,"description":"One value from the previous call's nextCursors. Omit for the first page."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"description":"How many of each kind to read, 1 to 80. Default 40."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/images":{"post":{"operationId":"create_image","summary":"Create an image","description":"Generate one image: a product photo, a model shot, an ad image, a social post (Instagram, Facebook, TikTok), a catalog or campaign picture, including a remake, another version or a new pose, angle or scene of an earlier one. Use it when they ask to make a photo or an ad picture, shoot their product, put it on a model or try another angle. Saved products and characters passed by id keep their exact look. An ad, a campaign or a matching set has a playbook: load it from get_instructions first. Omit model for the workspace default; when the person leaves details open, choose them. Use imageCount for variants of one prompt; for 2 to 12 different shots use create_images instead. To change an existing picture use edit_image, to make one sharper or bigger upscale_image, to give one a ready-made look apply_style; a clip is create_video. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn. ignoredSettings lists anything the model could not use.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":32000,"description":"What to shoot, in one short line."},"productIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved product ids from list_products; each keeps its exact look."},"characterIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved character ids from list_characters; each keeps its face."},"assetIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved asset ids from list_assets, used as reference pictures."},"referenceImageUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":14,"description":"Pictures to follow, like a place or a look: links from save_attached_files or upload_file, a shot's output links, or a public link. Every image model takes them, wings included. Each is copied into the workspace first."},"studioId":{"type":"string","maxLength":100,"description":"A studio id from list_studios, only when the person names a studio: it replaces the whole scene."},"folderId":{"type":"string","maxLength":100,"description":"A folder id from list_folders: the finished shot is saved into it."},"aspectRatio":{"type":"string","maxLength":20,"description":"Frame shape like 4:5 or 16:9, from the model's aspectRatios in list_models. Omit for the default."},"model":{"type":"string","maxLength":100,"description":"An image model id from list_models. Omit for the workspace default. An unlisted id is refused, never swapped."},"imageCount":{"type":"integer","minimum":1,"maximum":4,"description":"Variants of this one prompt and these settings, 1 to 4, each charged. Different shots go in create_images. Models marked oneImageOnly make one."},"imageSize":{"type":"string","enum":["1K","2K","4K"],"description":"From the model's imageSizes; bigger costs more. Omit for its defaultImageSize. On a model with imageSizeQualities the size sets the quality, not the pixels: 1K = low, 2K = medium, 4K = high."},"quality":{"type":"string","enum":["low","medium","high","xhigh","max"],"description":"Rendering quality, from the model's qualities in list_models; higher costs more. With it, imageSize is the real frame size. Omit to let imageSize set the quality as before. low: Quick drafts, lowest price; medium: Balanced detail and price; high: Fine detail for final images; xhigh: Extra detail; max: The most detail."},"background":{"type":"string","enum":["auto","opaque","transparent"],"description":"From the model's backgrounds in list_models. auto: Picked for your prompt; opaque: Always a filled background; transparent: No background, a clean cutout."},"maxResolution":{"type":"boolean","description":"Older switch for 4K; imageSize wins when both are sent."},"recraftStyleId":{"type":"string","maxLength":100,"description":"The style id the first shot of a set returned. Pass it on every later shot so the set matches; without it each shot rebuilds its style from the references, which costs credits and drifts."},"wingsIntent":{"type":"string","maxLength":500,"description":"wings model only: one line on what its second pass should keep, like the logo crisp."},"wingsEditModel":{"type":"string","maxLength":100,"description":"wings model only: which of list_models editModels runs its second pass. Omit for the workspace default."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"additionalProperties":false}}}}}},"/v1/images/batch":{"post":{"operationId":"create_images","summary":"Create several different images","description":"Generate up to 12 different images in one call, one prompt each: a set with one shot per look, angle or product. Use it when they ask for a set, a catalog, several looks or one shot per product. For one shot, or variants of one prompt, use create_image with imageCount. Spends credits for each shot that starts; getCost: true prices every shot and starts none. A refused shot is reported against its index while the rest still run. On a timeout, retry with the same idempotencyKey: shots that already started come back unchanged and are not charged again. Returns results [{ index, generationId, status }] in the order sent; then wait_generations on every started id and one get_generations, in the same turn.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"string","maxLength":32000,"description":"What to shoot, in one short line."},"productIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved product ids from list_products; each keeps its exact look."},"characterIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved character ids from list_characters; each keeps its face."},"assetIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved asset ids from list_assets, used as reference pictures."},"referenceImageUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":14,"description":"Pictures to follow, like a place or a look: links from save_attached_files or upload_file, a shot's output links, or a public link. Every image model takes them, wings included. Each is copied into the workspace first."},"studioId":{"type":"string","maxLength":100,"description":"A studio id from list_studios, only when the person names a studio: it replaces the whole scene."},"folderId":{"type":"string","maxLength":100,"description":"A folder id from list_folders: the finished shot is saved into it."},"aspectRatio":{"type":"string","maxLength":20,"description":"Frame shape like 4:5 or 16:9, from the model's aspectRatios in list_models. Omit for the default."},"model":{"type":"string","maxLength":100,"description":"An image model id from list_models. Omit for the workspace default. An unlisted id is refused, never swapped."},"imageSize":{"type":"string","enum":["1K","2K","4K"],"description":"From the model's imageSizes; bigger costs more. Omit for its defaultImageSize. On a model with imageSizeQualities the size sets the quality, not the pixels: 1K = low, 2K = medium, 4K = high."},"quality":{"type":"string","enum":["low","medium","high","xhigh","max"],"description":"Rendering quality, from the model's qualities in list_models; higher costs more. With it, imageSize is the real frame size. Omit to let imageSize set the quality as before. low: Quick drafts, lowest price; medium: Balanced detail and price; high: Fine detail for final images; xhigh: Extra detail; max: The most detail."},"background":{"type":"string","enum":["auto","opaque","transparent"],"description":"From the model's backgrounds in list_models. auto: Picked for your prompt; opaque: Always a filled background; transparent: No background, a clean cutout."},"maxResolution":{"type":"boolean","description":"Older switch for 4K; imageSize wins when both are sent."},"recraftStyleId":{"type":"string","maxLength":100,"description":"The style id the first shot of a set returned. Pass it on every later shot so the set matches; without it each shot rebuilds its style from the references, which costs credits and drifts."},"wingsIntent":{"type":"string","maxLength":500,"description":"wings model only: one line on what its second pass should keep, like the logo crisp."},"wingsEditModel":{"type":"string","maxLength":100,"description":"wings model only: which of list_models editModels runs its second pass. Omit for the workspace default."},"index":{"type":"integer","minimum":0,"description":"Your own number for this shot, echoed back. Keep it the same on a retry."}},"required":["index"],"additionalProperties":false},"minItems":1,"maxItems":12,"description":"The shots to start, 1 to 12."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["requests"],"additionalProperties":false}}}}}},"/v1/images/edit":{"post":{"operationId":"edit_image","summary":"Edit an image","description":"Change a specific existing image and keep everything the prompt does not name: remove a background, swap a wall, recolour a garment, place a logo. Use it when they ask to remove the background, change a colour, add their logo or fix something in this picture. A new shot, a remake, another version, or a new pose, angle, framing or scene goes to create_image even when an earlier image exists: it holds faces and garments far more exactly. A ready-made look is apply_style; sharper or bigger is upscale_image. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":32000,"description":"The change, in plain words; everything not named stays as it is."},"imageUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"minItems":1,"maxItems":14,"description":"Links from save_attached_files or upload_file, a shot's output links, or a public link. The first is the image to edit; the rest are extra pictures the edit can use (a logo, a swatch). Each is copied into the workspace first."},"productIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved product ids from list_products to keep exact through the edit."},"characterIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved character ids from list_characters to keep exact through the edit."},"aspectRatio":{"type":"string","enum":["9:16","2:3","4:5","1:1","5:4","3:2","16:9","21:9"],"description":"Omit to keep the source image's own shape."},"maxResolution":{"type":"boolean","description":"Render at 4K, at a higher price. Omit for the standard size."},"quality":{"type":"string","enum":["low","medium","high","xhigh","max"],"description":"Rendering quality, from the edit model's qualities in list_models; higher costs more. Omit for its default. low: Quick drafts, lowest price; medium: Balanced detail and price; high: Fine detail for final images; xhigh: Extra detail; max: The most detail."},"background":{"type":"string","enum":["auto","opaque","transparent"],"description":"From the edit model's backgrounds in list_models. auto: Picked for your prompt; opaque: Always a filled background; transparent: No background, a clean cutout."},"variantCount":{"type":"integer","minimum":1,"maximum":4,"description":"How many versions, 1 to 4, each charged. Default 1."},"editModel":{"type":"string","maxLength":100,"description":"Which of list_models editModels runs the edit. Omit for the workspace default."},"parentGenerationId":{"type":"string","maxLength":100,"description":"The id of the image or video this one came from, to keep them linked in the history."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["prompt","imageUrls"],"additionalProperties":false}}}}}},"/v1/images/upscale":{"post":{"operationId":"upscale_image","summary":"Upscale an image","description":"Make one finished image sharper or bigger, for print or a large crop, without changing what is in it (that is edit_image; a clip is upscale_video). Use it when they ask to upscale, sharpen, enhance or make an image bigger or high resolution. Upscalers: recraft: Sharpens what is already there and keeps the size. seedvr: Rebuilds the shot at the size you pick, up to 4K. bria: Doubles the width and height of the picture and keeps see-through backgrounds see-through. topaz: Doubles the width and height of the picture and keeps fine detail like fabric, skin and print. Omit upscaler for recraft. Only seedvr takes target; a target sent to the others is refused. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"generationId":{"type":"string","minLength":1,"maxLength":100,"description":"The id of the set the image is in, from get_generation or list_generations."},"imageIndex":{"type":"integer","minimum":0,"maximum":49,"description":"The image's position in that set, from 0."},"imageUrl":{"type":"string","format":"uri","maxLength":2048,"description":"That image's output link, to pick it by link; one that matches none of the outputs falls back to imageIndex."},"upscaler":{"type":"string","enum":["recraft","seedvr","bria","topaz"],"description":"Omit for recraft."},"target":{"type":"string","enum":["720p","1080p","1440p","2160p"],"description":"Output size, seedvr only. Bigger costs more."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["generationId","imageIndex"],"additionalProperties":false}}}}}},"/v1/videos":{"post":{"operationId":"create_video","summary":"Create a video","description":"Generate one short clip from a prompt, with optional first and last frames and reference pictures, clips or sound: a product video, a reel, a TikTok, a UGC clip or one shot of a video ad or commercial. Use it when they ask to make a video, animate this photo, turn it into a clip or make a reel. Saved products and characters passed by id keep their exact look. A video ad, UGC ad or commercial has a playbook: load it from get_instructions first. Omit videoModel for the workspace default. For 2 to 12 different clips use create_videos; to change a clip use edit_video, to continue one extend_video, to copy a clip's movement onto a photo motion_control. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn. ignoredSettings lists anything the model could not use.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved product ids from list_products; each keeps its exact look."},"characterIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved character ids from list_characters; each keeps its face."},"assetIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved asset ids from list_assets, used as reference pictures."},"folderId":{"type":"string","maxLength":100,"description":"A folder id from list_folders: the finished shot is saved into it."},"aspectRatio":{"type":"string","maxLength":20,"description":"Frame shape like 4:5 or 16:9, from the model's aspectRatios in list_models. Omit for the default."},"videoModel":{"type":"string","maxLength":100,"description":"A video slug from list_models. Omit for the workspace default (videoDefault)."},"resolution":{"type":"string","maxLength":20,"description":"From the model's resolutions. Omit for its defaultResolution; higher costs more per second."},"duration":{"type":"integer","description":"Whole seconds within the model's minDurationSec to maxDurationSec; there is no auto length."},"generateAudio":{"type":"boolean","description":"Make sound with the clip, on models whose audio is true."},"bitrateMode":{"type":"string","enum":["standard","high"],"description":"Encode quality at the same price, on models that list bitrateModes. Omit for the model's own default."},"watermark":{"type":"boolean","description":"On models with supportsWatermark. Elsewhere it is left out and listed in ignoredSettings."},"seed":{"type":"integer","description":"On models with supportsSeed. Elsewhere it is left out and listed in ignoredSettings."},"videoDraft":{"type":"boolean","description":"A quick 480p preview, priced as a 480p clip, on models with supportsDraft. Leave resolution out."},"prompt":{"type":"string","maxLength":32000,"description":"What happens in the clip: a short shot-by-shot direction."},"referenceImageUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":14,"description":"Pictures the clip should follow: links from save_attached_files or upload_file, a shot's output links, or a public link. Only models with maxReferenceImages above zero read them. Each is copied into the workspace first."},"startFrameUrl":{"type":"string","format":"uri","maxLength":2048,"description":"Public image link for the first frame."},"endFrameUrl":{"type":"string","format":"uri","maxLength":2048,"description":"Public image link for the last frame, on models with supportsEndFrame."},"videoReferenceUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":10,"description":"Clips that guide the movement and look, each an MP4 link. Only models with maxReferenceVideos above zero."},"audioReferenceUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":10,"description":"Sound that drives the clip, each a WAV link. Only models with maxReferenceAudios above zero. A voice's previewUrl or sampleUrl from list_voices makes the clip speak the prompt's words in that voice; a previewUrl is an MP3, so only on models whose referenceAudioFormats take MP3."},"cameraMovement":{"type":"string","enum":["dolly_in","dolly_out","dolly_left","dolly_right","jib_up","jib_down","static","focus_shift"],"description":"How the camera moves: dolly_in, dolly_out, dolly_left, dolly_right, jib_up, jib_down, static, focus_shift, on models that list cameraMovements. Omit to let the model choose."},"multiPrompt":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":512,"description":"What happens in this shot."},"duration":{"type":"integer","minimum":1,"description":"This shot's length in whole seconds."}},"required":["prompt"],"additionalProperties":false},"minItems":1,"maxItems":6,"description":"Shots in order, their lengths adding up to duration, on models with supportsMultiPrompt; list_models says how many each chains."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"additionalProperties":false}}}}}},"/v1/videos/batch":{"post":{"operationId":"create_videos","summary":"Create several different videos","description":"Generate up to 12 different clips in one call, one prompt each, each with create_video's settings. Use it when they ask for several clips, a batch of reels or one video per product. For one clip use create_video. Spends credits for each shot that starts; getCost: true prices every shot and starts none. A refused shot is reported against its index while the rest still run. On a timeout, retry with the same idempotencyKey: shots that already started come back unchanged and are not charged again. Returns results [{ index, generationId, status }] in the order sent; then wait_generations on every started id and one get_generations, in the same turn.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","items":{"type":"object","properties":{"productIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved product ids from list_products; each keeps its exact look."},"characterIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved character ids from list_characters; each keeps its face."},"assetIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved asset ids from list_assets, used as reference pictures."},"folderId":{"type":"string","maxLength":100,"description":"A folder id from list_folders: the finished shot is saved into it."},"aspectRatio":{"type":"string","maxLength":20,"description":"Frame shape like 4:5 or 16:9, from the model's aspectRatios in list_models. Omit for the default."},"videoModel":{"type":"string","maxLength":100,"description":"A video slug from list_models. Omit for the workspace default (videoDefault)."},"resolution":{"type":"string","maxLength":20,"description":"From the model's resolutions. Omit for its defaultResolution; higher costs more per second."},"duration":{"type":"integer","description":"Whole seconds within the model's minDurationSec to maxDurationSec; there is no auto length."},"generateAudio":{"type":"boolean","description":"Make sound with the clip, on models whose audio is true."},"bitrateMode":{"type":"string","enum":["standard","high"],"description":"Encode quality at the same price, on models that list bitrateModes. Omit for the model's own default."},"watermark":{"type":"boolean","description":"On models with supportsWatermark. Elsewhere it is left out and listed in ignoredSettings."},"seed":{"type":"integer","description":"On models with supportsSeed. Elsewhere it is left out and listed in ignoredSettings."},"videoDraft":{"type":"boolean","description":"A quick 480p preview, priced as a 480p clip, on models with supportsDraft. Leave resolution out."},"prompt":{"type":"string","maxLength":32000,"description":"What happens in the clip: a short shot-by-shot direction."},"referenceImageUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":14,"description":"Pictures the clip should follow: links from save_attached_files or upload_file, a shot's output links, or a public link. Only models with maxReferenceImages above zero read them. Each is copied into the workspace first."},"startFrameUrl":{"type":"string","format":"uri","maxLength":2048,"description":"Public image link for the first frame."},"endFrameUrl":{"type":"string","format":"uri","maxLength":2048,"description":"Public image link for the last frame, on models with supportsEndFrame."},"videoReferenceUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":10,"description":"Clips that guide the movement and look, each an MP4 link. Only models with maxReferenceVideos above zero."},"audioReferenceUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":10,"description":"Sound that drives the clip, each a WAV link. Only models with maxReferenceAudios above zero. A voice's previewUrl or sampleUrl from list_voices makes the clip speak the prompt's words in that voice; a previewUrl is an MP3, so only on models whose referenceAudioFormats take MP3."},"cameraMovement":{"type":"string","enum":["dolly_in","dolly_out","dolly_left","dolly_right","jib_up","jib_down","static","focus_shift"],"description":"How the camera moves: dolly_in, dolly_out, dolly_left, dolly_right, jib_up, jib_down, static, focus_shift, on models that list cameraMovements. Omit to let the model choose."},"multiPrompt":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":512,"description":"What happens in this shot."},"duration":{"type":"integer","minimum":1,"description":"This shot's length in whole seconds."}},"required":["prompt"],"additionalProperties":false},"minItems":1,"maxItems":6,"description":"Shots in order, their lengths adding up to duration, on models with supportsMultiPrompt; list_models says how many each chains."},"index":{"type":"integer","minimum":0,"description":"Your own number for this shot, echoed back. Keep it the same on a retry."}},"required":["index"],"additionalProperties":false},"minItems":1,"maxItems":12,"description":"The shots to start, 1 to 12."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["requests"],"additionalProperties":false}}}}}},"/v1/videos/edit":{"post":{"operationId":"edit_video","summary":"Edit a video","description":"Change one existing clip by prompt (a new setting, outfit or object) and keep its movement. Use it when they ask to change the background of a clip, swap the outfit or replace something in their video. Pick a videoModel with maxReferenceVideos above zero in list_models, or omit it for the workspace default. A new clip is create_video. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn. ignoredSettings lists anything the model could not use.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved product ids from list_products; each keeps its exact look."},"characterIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved character ids from list_characters; each keeps its face."},"assetIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved asset ids from list_assets, used as reference pictures."},"folderId":{"type":"string","maxLength":100,"description":"A folder id from list_folders: the finished shot is saved into it."},"aspectRatio":{"type":"string","maxLength":20,"description":"Frame shape like 4:5 or 16:9, from the model's aspectRatios in list_models. Omit for the default."},"videoModel":{"type":"string","maxLength":100,"description":"A video slug from list_models. Omit for the workspace default (videoDefault)."},"resolution":{"type":"string","maxLength":20,"description":"From the model's resolutions. Omit for its defaultResolution; higher costs more per second."},"duration":{"type":"integer","description":"Whole seconds within the model's minDurationSec to maxDurationSec; there is no auto length."},"generateAudio":{"type":"boolean","description":"Make sound with the clip, on models whose audio is true."},"bitrateMode":{"type":"string","enum":["standard","high"],"description":"Encode quality at the same price, on models that list bitrateModes. Omit for the model's own default."},"watermark":{"type":"boolean","description":"On models with supportsWatermark. Elsewhere it is left out and listed in ignoredSettings."},"seed":{"type":"integer","description":"On models with supportsSeed. Elsewhere it is left out and listed in ignoredSettings."},"videoDraft":{"type":"boolean","description":"A quick 480p preview, priced as a 480p clip, on models with supportsDraft. Leave resolution out."},"prompt":{"type":"string","maxLength":32000,"description":"What happens in the clip: a short shot-by-shot direction."},"referenceImageUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":14,"description":"Pictures the clip should follow: links from save_attached_files or upload_file, a shot's output links, or a public link. Only models with maxReferenceImages above zero read them. Each is copied into the workspace first."},"videoReferenceUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"minItems":1,"maxItems":1,"description":"The one clip to change: an MP4 link."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["videoReferenceUrls"],"additionalProperties":false}}}}}},"/v1/videos/extend":{"post":{"operationId":"extend_video","summary":"Extend a video","description":"Continue an existing clip: the new clip picks up where startVideoUrl ends, on Seedance 2.5 or Seedance 2.5 Flash or Gemini Omni 1.1 Flash or Gemini Omni 1.2 Flash. Use it when they ask to make a clip longer, keep it going or add what happens next. To change a clip instead, use edit_video. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn. ignoredSettings lists anything the model could not use.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved product ids from list_products; each keeps its exact look."},"characterIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved character ids from list_characters; each keeps its face."},"assetIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved asset ids from list_assets, used as reference pictures."},"folderId":{"type":"string","maxLength":100,"description":"A folder id from list_folders: the finished shot is saved into it."},"aspectRatio":{"type":"string","maxLength":20,"description":"Frame shape like 4:5 or 16:9, from the model's aspectRatios in list_models. Omit for the default."},"videoModel":{"type":"string","enum":["bytedance/seedance-2.5","bytedance/seedance-2.5-flash","gemini-omni-1.1-flash","gemini-omni-1.2-flash"],"description":"The model that continues the clip."},"resolution":{"type":"string","maxLength":20,"description":"From the model's resolutions. Omit for its defaultResolution; higher costs more per second."},"duration":{"type":"integer","description":"Whole seconds within the model's minDurationSec to maxDurationSec; there is no auto length."},"generateAudio":{"type":"boolean","description":"Make sound with the clip, on models whose audio is true."},"bitrateMode":{"type":"string","enum":["standard","high"],"description":"Encode quality at the same price, on models that list bitrateModes. Omit for the model's own default."},"watermark":{"type":"boolean","description":"On models with supportsWatermark. Elsewhere it is left out and listed in ignoredSettings."},"seed":{"type":"integer","description":"On models with supportsSeed. Elsewhere it is left out and listed in ignoredSettings."},"videoDraft":{"type":"boolean","description":"A quick 480p preview, priced as a 480p clip, on models with supportsDraft. Leave resolution out."},"prompt":{"type":"string","maxLength":32000,"description":"What happens in the clip: a short shot-by-shot direction."},"referenceImageUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":14,"description":"Pictures the clip should follow: links from save_attached_files or upload_file, a shot's output links, or a public link. Only models with maxReferenceImages above zero read them. Each is copied into the workspace first."},"startVideoUrl":{"type":"string","format":"uri","maxLength":2048,"description":"The clip to continue: an MP4 link."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["videoModel","startVideoUrl"],"additionalProperties":false}}}}}},"/v1/videos/motion":{"post":{"operationId":"motion_control","summary":"Copy a clip's movement onto a photo","description":"Make the person in a photo (startFrameUrl) move exactly like a driving clip (startVideoUrl); the driving clip sets the length. Use it when they ask to make this person do that dance, copy the moves from a video or match a clip's motion. To remake a whole clip with their product or face, use main_character. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn. ignoredSettings lists anything the model could not use.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"characterIds":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":14,"description":"Saved character ids from list_characters; each keeps its face."},"folderId":{"type":"string","maxLength":100,"description":"A folder id from list_folders: the finished shot is saved into it."},"resolution":{"type":"string","maxLength":20,"description":"From the model's resolutions. Omit for its defaultResolution; higher costs more per second."},"characterOrientation":{"type":"string","enum":["image","video"],"description":"'video' follows the clip's framing and takes a clip up to 30 seconds. 'image' keeps the photo's framing and takes a clip up to 10 seconds."},"keepOriginalSound":{"type":"boolean","description":"Keep the driving clip's own sound."},"prompt":{"type":"string","maxLength":32000,"description":"What happens in the clip: a short shot-by-shot direction."},"duration":{"type":"integer","description":"The driving clip sets the length: omit this, or keep it inside the model's drivingClipSeconds."},"videoModel":{"type":"string","enum":["kwaivgi/kling-v3-motion-control"],"description":"The motion control model."},"startFrameUrl":{"type":"string","format":"uri","maxLength":2048,"description":"Public image link of the person who should move."},"startVideoUrl":{"type":"string","format":"uri","maxLength":2048,"description":"The driving clip whose movement is copied: an MP4 link."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["videoModel","startFrameUrl","startVideoUrl"],"additionalProperties":false}}}}}},"/v1/videos/upscale":{"post":{"operationId":"upscale_video","summary":"Upscale a video","description":"Make a finished clip sharper or bigger, at 1080p, 2K, or 4K, without changing what happens in it (that is edit_video; a picture is upscale_image). Use it when they ask to upscale, sharpen, enhance or raise the quality of a video. Upscalers: flux: Makes a clip sharper at 1080p, 2K or 4K. Precise keeps it as it is; Creative adds fine detail. target 1080p (1080p), 1440p (2K), 2160p (4K); mode precise or creative, default precise. Clips up to 20 seconds and 50 MB. topaz: Makes a clip sharper at 1080p, 2K or 4K, up to 5 minutes. Precise keeps it as it is; Creative adds realism to AI video. target 1080p (1080p), 1440p (2K), 2160p (4K); mode precise or creative, default precise. Clips up to 300 seconds and 100 MB, up to 30 frames a second. astra: Makes a clip 4K and adds new detail where the original has too little, up to 5 minutes. target 2160p (4K); mode creative, default creative. Clips up to 300 seconds and 100 MB, up to 30 frames a second. Omit upscaler for flux. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"generationId":{"type":"string","minLength":1,"maxLength":100,"description":"The clip's id, from get_generation or list_generations."},"upscaler":{"type":"string","enum":["flux","topaz","astra"],"description":"Omit for flux."},"target":{"type":"string","enum":["1080p","1440p","2160p"],"description":"Output size; each upscaler takes the sizes listed for it. Bigger costs more."},"mode":{"type":"string","enum":["precise","creative"],"description":"precise or creative. Omit for precise; creative costs more."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["generationId"],"additionalProperties":false}}}}}},"/v1/audio/speech":{"post":{"operationId":"create_speech","summary":"Read a script aloud","description":"Reads a script aloud in one voice, or a conversation in several, and saves it as a sound file: a voiceover, narration or ad line. Use it when they ask for a voiceover, narration, an audio ad or someone to read this out. A new voice on an existing recording is change_voice; a video in another language is translate_video. list_models with type audio gives each model's voices, languages, settings, maxScriptChars and the cues it reads inside a script (tags). Some models charge by how long the result runs: the price is the most it can cost, and what goes unused comes back when it finishes. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn. A finished sound file comes back as audioUrl, a finished clip as videoUrl.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"script":{"type":"string","minLength":1,"maxLength":10000,"description":"What the voice says, up to the model's maxScriptChars. Send this or speakers."},"speakers":{"type":"array","items":{"type":"object","properties":{"voice":{"type":"string","maxLength":100,"description":"A voice id from the model's voices in list_models."},"text":{"type":"string","minLength":1,"maxLength":10000,"description":"What this voice says."}},"required":["voice","text"],"additionalProperties":false},"minItems":1,"maxItems":50,"description":"A conversation, one line per turn in order, in place of script and voice. Only models with speakers in list_models take it (gemini-3.8-flash-tts, eleven-v3), up to their maxVoices voices."},"model":{"type":"string","maxLength":100,"description":"A slug from list_models with type audio. Omit for gemini-3.8-flash-tts."},"voice":{"type":"string","maxLength":100,"description":"A voice id from the model's voices in list_models, from list_voices with model (every voice it has), or one of the workspace's own from list_voices (on minimax-speech-2.8-hd, minimax-speech-2.8-turbo, seed-audio-1). Omit for the model's default voice."},"language":{"type":"string","maxLength":100,"description":"A language code from the model's languages in list_models. Omit to read in the script's own language."},"settings":{"type":"object","properties":{"style":{"type":"string","maxLength":2000,"description":"Voice details: a short note in words."},"stability":{"type":"number","description":"Stability: a number within the model's min and max."},"similarity":{"type":"number","description":"Similarity: a number within the model's min and max."},"emotion":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Mood: one of the model's option values."},"intensity":{"type":"number","description":"Intensity: a number within the model's min and max."},"timbre":{"type":"number","description":"Tone: a number within the model's min and max."},"speed":{"type":"number","description":"Speed: a number within the model's min and max."},"pitch":{"type":"number","description":"Pitch: a number within the model's min and max."},"volume":{"type":"number","description":"Volume: a number within the model's min and max."},"sampleRate":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Sample rate: one of the model's option values."},"normalizeText":{"type":"boolean","description":"Numbers as words: true or false."},"outputFormat":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Output format: one of the model's option values."},"multilingual":{"type":"boolean","description":"Other languages: true or false."},"removeNoise":{"type":"boolean","description":"Remove noise: true or false."}},"additionalProperties":false,"description":"Only the settings the model lists under settings in list_models: a number within its min and max, one of its option values, a note, or on/off."},"folderId":{"type":"string","maxLength":100,"description":"A folder id from list_folders: the finished file is saved into it."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"additionalProperties":false}}}}}},"/v1/audio/voice-change":{"post":{"operationId":"change_voice","summary":"Change the voice on a recording","description":"Puts another voice on a recording or a clip, keeping the words and the timing; a clip comes back as the same clip with the new voice. Use it when they ask to change the voice, put another voice on this or redo the voiceover in a different voice. On eleven-voice-changer a sound file runs up to 300 seconds and a video up to 60. A file of theirs comes in through save_attached_files, or upload_file for a video. Reading a script in a voice is create_speech. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn. A finished sound file comes back as audioUrl, a finished clip as videoUrl.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceUrl":{"type":"string","format":"uri","maxLength":2048,"description":"The recording or clip, a link to an MP4 video, or a WAV, MP3 or M4A sound file: a public link, or one from this workspace such as a finished video or audio file."},"model":{"type":"string","maxLength":100,"description":"A slug from list_models with type audio. Omit for eleven-voice-changer."},"voice":{"type":"string","maxLength":100,"description":"A voice id from the model's voices in list_models. Omit for the model's default voice."},"settings":{"type":"object","properties":{"style":{"type":"string","maxLength":2000,"description":"Voice details: a short note in words."},"stability":{"type":"number","description":"Stability: a number within the model's min and max."},"similarity":{"type":"number","description":"Similarity: a number within the model's min and max."},"emotion":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Mood: one of the model's option values."},"intensity":{"type":"number","description":"Intensity: a number within the model's min and max."},"timbre":{"type":"number","description":"Tone: a number within the model's min and max."},"speed":{"type":"number","description":"Speed: a number within the model's min and max."},"pitch":{"type":"number","description":"Pitch: a number within the model's min and max."},"volume":{"type":"number","description":"Volume: a number within the model's min and max."},"sampleRate":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Sample rate: one of the model's option values."},"normalizeText":{"type":"boolean","description":"Numbers as words: true or false."},"outputFormat":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Output format: one of the model's option values."},"multilingual":{"type":"boolean","description":"Other languages: true or false."},"removeNoise":{"type":"boolean","description":"Remove noise: true or false."}},"additionalProperties":false,"description":"Only the settings the model lists under settings in list_models: a number within its min and max, one of its option values, a note, or on/off."},"folderId":{"type":"string","maxLength":100,"description":"A folder id from list_folders: the finished file is saved into it."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["sourceUrl"],"additionalProperties":false}}}}}},"/v1/audio/translate":{"post":{"operationId":"translate_video","summary":"Translate a video","description":"Makes a video speak another language in the speaker's own voice. Use it when they ask to translate a video, dub it into another language or make it speak Spanish. Use it only on videos of people who agreed to have their voice and words translated, never to make someone appear to say something they did not. Models with lipSync true in list_models (type audio) also move the lips to the new words; the others change only the voice, and those that accept audio take a sound file too. A new voice in the same language is change_voice. Some models charge by how long the result runs: the price is the most it can cost, and what goes unused comes back when it finishes. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn. A finished sound file comes back as audioUrl, a finished clip as videoUrl.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceUrl":{"type":"string","format":"uri","maxLength":2048,"description":"The recording or clip, a link to an MP4 video, or a WAV, MP3 or M4A sound file: a public link, or one from this workspace such as a finished video or audio file."},"language":{"type":"string","minLength":1,"maxLength":100,"description":"The language to speak: a code from the model's languages in list_models."},"model":{"type":"string","maxLength":100,"description":"A slug from list_models with type audio. Omit for heygen-translate."},"folderId":{"type":"string","maxLength":100,"description":"A folder id from list_folders: the finished file is saved into it."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["sourceUrl","language"],"additionalProperties":false}}}}}},"/v1/styles":{"get":{"operationId":"list_styles","summary":"List styles","description":"List the ready-made looks a photo or clip can take, each with a before and after sample. Use it when they ask what styles there are, name a look or want to see the options. Pass a style's id to apply_style; only listed looks exist.","parameters":[{"name":"medium","in":"query","required":false,"schema":{"type":"string","enum":["image","video"],"description":"image for photo styles, video for clip styles. Omit for both."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/styles/{styleId}/apply":{"post":{"operationId":"apply_style","summary":"Apply a style","description":"Give one of their photos or clips a look from list_styles: a photo style takes a photo, a video style a clip. Use it when they ask to apply a style, give this photo a look or make it look like one of the samples. Any other change is edit_image or edit_video. Spends credits; getCost: true returns the price and makes nothing. Returns its id at status pending: call wait_generations with it, then get_generations to show it, in the same turn.","parameters":[{"name":"styleId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"styleId":{"type":"string","minLength":1,"maxLength":64,"description":"A style id from list_styles."},"sourceUrl":{"type":"string","format":"uri","maxLength":2048,"description":"The photo or clip: a link from save_attached_files or upload_file, a shot's output link, or a public link."},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["styleId","sourceUrl"],"additionalProperties":false}}}}}},"/v1/generations":{"get":{"operationId":"list_generations","summary":"List images, videos and audio","description":"List the workspace's images, videos and audio, newest first, one page at a time. Use it when they ask to see their recent work, find an earlier shot, or show, edit, upscale or build on one from before; for an id you already have, use get_generation. Returns { data, nextCursor }. Pass nextCursor back as cursor for the next page; null means there are no more.","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"nextCursor from the previous page. Omit for the first page."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Page size, 1 to 200. Default 20."}},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Only shots whose prompt contains this text."}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["IMAGE","VIDEO","AUDIO"],"description":"Only this kind. Omitted, sound files are left out; AUDIO lists them."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/generations/{generationId}":{"get":{"operationId":"get_generation","summary":"Get an image, video or audio","description":"Get one image, video or audio by id: its status, type, settings and, once completed, the links to its images, clip or sound file in output. Use it when they ask whether a shot is done, why it failed, or for its link or settings. To wait for ones you just started, use wait_generations rather than calling this in a loop; to show several, use get_generations. A failed one says so, and its credits come back on their own.","parameters":[{"name":"generationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/products":{"get":{"operationId":"list_products","summary":"List products","description":"List saved products, the items whose real color, logo and stitching a shot keeps. Use it when they ask to see their products, find a product, or shoot one of theirs (\"my bag\", \"our sneaker\"), and pass the id as productIds; a shot that describes its own subject needs no saved product. People are in list_characters, loose reference pictures in list_assets. The shared catalog (isGlobal) comes first, then the workspace's own, newest first. Returns data (id, name, description, imageUrls, analysis, isGlobal) and nextCursor. Pass nextCursor back as cursor for the next page; null means there are no more.","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Part of a name to match. Omit to list the newest."}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["own","global","all"],"description":"own: only this workspace's. global: only the shared catalog. all (default): both, shared first."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128,"description":"nextCursor from the previous page. Omit for the first page."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Page size, 1 to 200. Default 200."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"create_product","summary":"Create product","description":"Save a product so every shot keeps its real color, logo and stitching. Use it when they ask to save or add a product, or to keep it exactly the same in every shot. Send one clear photo of one side; another side of the same item is its own product (\"Sand Dune back\"). Use a real photo, not a shot Icarus made: a product is pinned to its photo, so a render's mistakes would carry into every later shot. Returns the product (id, name, imageUrls); a photo saved before returns that one with alreadySaved: true instead of a copy. Pass the id as productIds on create_image or create_video. A person is create_character; a loose reference picture is create_asset.","parameters":[],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Product name."},"description":{"type":"string","maxLength":2000,"description":"Notes about the product. Optional."},"imageUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":14,"description":"Public image links, each copied into the workspace."}},"required":["name"],"additionalProperties":false}}}}}},"/v1/products/{productId}":{"get":{"operationId":"get_product","summary":"Get product","description":"Get one saved product by id, with its photos and analysis. Use it when they ask about a product's details or photos and you have its id. To find one by name, use list_products with search. Returns id, name, description, imageUrls, analysis, isGlobal.","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/characters":{"get":{"operationId":"list_characters","summary":"List characters","description":"List saved characters, the models whose face stays the same in every shot. Use it when they ask to see their models, find a model, or shoot one of theirs (\"our model\", \"keep the face\"), and pass the id as characterIds; a shot that describes whoever is in it needs no saved character. Products are in list_products, loose reference pictures in list_assets. The shared catalog (isGlobal) comes first, then the workspace's own, newest first. Returns data (id, name, description, imageUrls, analysis, isGlobal) and nextCursor. Pass nextCursor back as cursor for the next page; null means there are no more.","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Part of a name to match. Omit to list the newest."}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["own","global","all"],"description":"own: only this workspace's. global: only the shared catalog. all (default): both, shared first."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128,"description":"nextCursor from the previous page. Omit for the first page."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Page size, 1 to 200. Default 200."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"create_character","summary":"Create character","description":"Save a character so the same face appears in every shot. Use it when they ask to save a model, keep this face or use the same person every time. Send one photo with a clear face; more photos make the face drift. For a real person use a real photo of them; for a made-up person use the casting photo or character sheet Icarus made, which is their original. Returns the character (id, name, imageUrls); a photo saved before returns that one with alreadySaved: true instead of a copy. Pass the id as characterIds on create_image or create_video. A product is create_product; a loose reference picture is create_asset.","parameters":[],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Character name."},"description":{"type":"string","maxLength":2000,"description":"Notes about the character. Optional."},"imageUrls":{"type":"array","items":{"type":"string","format":"uri","maxLength":2048},"maxItems":14,"description":"Public image links, each copied into the workspace."}},"required":["name"],"additionalProperties":false}}}}}},"/v1/characters/{characterId}":{"get":{"operationId":"get_character","summary":"Get character","description":"Get one saved character by id, with its photo and analysis. Use it when they ask about a model's details or photo and you have its id. To find one by name, use list_characters with search. Returns id, name, description, imageUrls, analysis, isGlobal.","parameters":[{"name":"characterId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/assets":{"get":{"operationId":"list_assets","summary":"List assets","description":"List the workspace's saved assets, newest first: reference pictures a person tags as @name in a prompt. Use it when they ask to see their references, find a saved picture or use one they tag as @name. Pass an id in assetIds on create_image or create_video. Many carry device names like 'Screenshot-2026-07-23', so a name search can miss one; omit search to see the newest. Returns data (id, name, imageUrl) and hasMore. There is no next page: at most 200 come back, so narrow with search. Products and characters have their own list tools.","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Part of a name to match. Omit to list the newest."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Page size, 1 to 200. Default 200."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"create_asset","summary":"Create asset","description":"Save one picture as an asset, a reference the person tags as @name in any prompt. Use it when they ask to save this as a reference, keep a picture to reuse or tag it as @name. Takes a shot from this workspace or a public PNG, JPEG or WEBP link of at most 50 MB. The name keeps letters, numbers, dashes and underscores, 32 characters at most. Returns the asset (id, name, imageUrl); a picture saved before returns that asset with alreadySaved: true. Products and characters have their own tools.","parameters":[],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Asset name, used as @name in prompts."},"imageUrl":{"type":"string","format":"uri","maxLength":2048,"description":"A public image link, or a shot's link from this workspace. It is copied in."}},"required":["name","imageUrl"],"additionalProperties":false}}}}}},"/v1/studios":{"get":{"operationId":"list_studios","summary":"List studios","description":"List saved studios: a scene (background, light, setting) saved once so a set looks the same. Use it only when they ask to see their studios or name one (\"our white studio\", \"the beach set\"), and pass its id as studioId on create_image; never pick one yourself, since a studio replaces the whole scene. Shared ones (isGlobal) come first, then the workspace's own, newest first. Returns data (id, name, thumbnail, isGlobal) and nextCursor; thumbnail is a preview picture or null. Pass nextCursor back as cursor for the next page; null means there are no more.","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["own","global","all"],"description":"own: only this workspace's. global: only the shared catalog. all (default): both, shared first."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128,"description":"nextCursor from the previous page. Omit for the first page."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Page size, 1 to 200. Default 200."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/folders":{"get":{"operationId":"list_folders","summary":"List folders","description":"List the workspace's folders (saved collections of shots), newest first, for the folderId add_to_folder and get_share_link take. Use it when they ask to see their folders, find one or save into a folder they name. Folders can sit inside folders: parentId is the folder each one is in, null at the top. The app calls a top-level folder a project, so a project they name is a folder here. Returns data (id, name, icon: its emoji or null, parentId) and nextCursor. Pass nextCursor back as cursor for the next page; null means there are no more. With search, it scans the newest 500 and returns at most 40 matches, with no next page.","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Part of a name to match. Omit to list the newest."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":128,"description":"nextCursor from the previous page. Omit for the first page."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Page size, 1 to 200. Default 200."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"create_folder","summary":"Create folder","description":"Make a new, empty folder, a collection to save shots into, at the top or inside another folder with parentId. Use it when they ask to make a project or a folder, start a collection or keep a set of shots together; a project is a folder at the top. Free. Folders go 5 levels deep at most. Returns its id, name and parentId; pass the id to add_to_folder.","parameters":[],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Folder name."},"parentId":{"type":"string","minLength":1,"maxLength":128,"description":"The folder to make it in, from list_folders or create_folder. Omit for the top level."}},"required":["name"],"additionalProperties":false}}}}}},"/v1/folders/{folderId}/items":{"post":{"operationId":"add_to_folder","summary":"Add shots to a folder","description":"Save shots that already exist into a folder, 1 to 50 in one call, each as its first picture. Use it when they ask to save these, keep them in a folder or add shots to a collection. Free; a picture already there is not added twice. If any shot isn't this workspace's, nothing is saved. Returns id, folderId, imageUrl and generationId of the saved picture; with generationIds, folderId, added (how many were new) and items.","parameters":[{"name":"folderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"generationIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":50,"description":"Every shot to save, from list_generations or the tool that made them."},"generationId":{"type":"string","minLength":1,"maxLength":128,"description":"One shot. Older calls send this; generationIds takes one or many. Pass imageUrl with it to pick a picture."},"folderId":{"type":"string","minLength":1,"maxLength":128,"description":"The folder's id, from list_folders or create_folder."},"imageUrl":{"type":"string","maxLength":2048,"description":"One of that shot's own output pictures, with generationId. Omit to save its first picture."}},"required":["folderId"],"additionalProperties":false}}}}}},"/v1/share-links":{"post":{"operationId":"get_share_link","summary":"Get a share link","description":"Make a public link anyone can open, to one shot (a picture, clip or sound) with generationId or to a whole folder with folderId, for the person to send or post. Use it when they ask for a link, to share a shot or folder, or to send it to someone. Free. A folder keeps one link; a shot gets a new link each call. Returns { url }.","parameters":[],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"generationId":{"type":"string","maxLength":128,"description":"The shot's id, from list_generations or the tool that made it. Not with folderId."},"fileUrl":{"type":"string","maxLength":2048,"description":"One of that shot's own outputs. Omit for its first one."},"folderId":{"type":"string","maxLength":128,"description":"The folder's id, from list_folders or create_folder. Not with generationId."}},"additionalProperties":false}}}}}},"/v1/voices":{"get":{"operationId":"list_voices","summary":"List voices","description":"Lists voices a page at a time, to pick one yourself. Use it when a voiceover or a speaking clip needs a voice and they left the choice to you. To let the person see, hear or choose one, use show_voices. With model: that voice model's voices, filtered by language, gender or words (a name, an accent); list_models shows only some of them, and its voiceCount says how many there are. Without model: the voices this workspace made from its own recordings, newest first, which read on minimax-speech-2.8-hd, minimax-speech-2.8-turbo, seed-audio-1; only status ready can be used. Returns data and nextCursor. Pass a voice's id as voice to create_speech.","parameters":[{"name":"model","in":"query","required":false,"schema":{"type":"string","enum":["gemini-3.8-flash-tts","eleven-v4","eleven-v4-turbo","eleven-v3","minimax-speech-2.8-hd","minimax-speech-2.8-turbo","qwen-audio-3","seed-speech-2","seed-audio-1","eleven-voice-changer"],"description":"A voice model's slug from list_models with type audio. Omit for the workspace's own voices."}},{"name":"language","in":"query","required":false,"schema":{"type":"string","maxLength":100,"description":"Only voices in this language, spelled as the voices' language field (\"Korean\"). Needs model."}},{"name":"gender","in":"query","required":false,"schema":{"type":"string","enum":["female","male","neutral"],"description":"Only voices of this gender. Needs model."}},{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":100,"description":"Words to find in a voice's name, language or accent. Needs model."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"nextCursor from the previous page. Omit for the first page."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Page size: up to 200 of a model's voices (default 60), up to 50 of the workspace's own (default 50)."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"create_voice","summary":"Make a voice from a recording","description":"Saves a voice from a 10 to 30 second recording of one person speaking (WAV or MP3), so create_speech can read in it on minimax-speech-2.8-hd, minimax-speech-2.8-turbo, seed-audio-1. Use it when they ask to clone their voice, make a voice from a recording or use their own voice. Only for the person's own voice, or one they have the speaker's permission to copy: ask them, and send consent true only when they say yes. A recording on their device comes in through upload_file with voiceRecording. Spends credits; getCost: true returns the price and makes nothing. Returns the voice at status creating; list_voices shows it ready within a minute.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceUrl":{"type":"string","format":"uri","maxLength":2048,"description":"The recording: a public link, or one from this workspace such as upload_file's."},"name":{"type":"string","minLength":1,"maxLength":40,"description":"What to call the voice."},"consent":{"type":"boolean","enum":[true],"description":"The person confirmed: \"This is my voice, or I have the speaker's permission to copy it.\""},"getCost":{"type":"boolean","description":"True returns the price in credits for these settings and makes nothing."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Any unique text for this request. Resending the same key returns the first result instead of charging again; reusing it with different settings is refused. On a timeout, resend with the same key, not a new one. Without a key, an identical request within five minutes returns the first result; send a new key to make it again on purpose."}},"required":["sourceUrl","name","consent"],"additionalProperties":false}}}}}},"/v1/voices/{voice}":{"patch":{"operationId":"rename_voice","summary":"Rename a voice","description":"Gives one of the workspace's own voices a new name. Use it when they ask to rename a voice or call it something else. Free. Returns the voice with its new name.","parameters":[{"name":"voice","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"voice":{"type":"string","minLength":1,"maxLength":200,"description":"The voice's id from list_voices (\"custom:...\")."},"name":{"type":"string","minLength":1,"maxLength":40,"description":"The new name."}},"required":["voice","name"],"additionalProperties":false}}}}},"delete":{"operationId":"delete_voice","summary":"Delete a voice","description":"Deletes the workspace's own voices and the recordings they were made from, for good; sound files already made in them stay. Use it when they ask to delete, remove or get rid of a voice. Pass every voice in voices, up to 50 in one call. A voice still being made can't be deleted yet, and one that isn't there changes nothing. Returns voice and deleted (true or false); with voices, one of those per voice, with why when one wasn't deleted.","parameters":[{"name":"voice","in":"path","required":true,"schema":{"type":"string"}},{"name":"voices","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"description":"The voice's id from list_voices (\"custom:...\")."},"minItems":1,"maxItems":50,"description":"Every voice to delete, from list_voices."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/uploads":{"post":{"operationId":"get_upload_link","summary":"Get a link to upload a file you have","description":"Get a private link to upload files you already hold (on disk or in your sandbox) into the workspace; the person sees nothing. Use it after you make or download a file yourself and need it in the workspace. Use a JPEG, PNG or WebP picture, an MP4 video, a WAV, MP3 or M4A sound file, a PDF, TXT, MD, CSV, DOCX, PPTX or XLSX document, or a JSON or ZIP file. Pictures up to 50 MB and videos up to 100 MB each. The link lasts 15 minutes. Returns { uploadLink, boxId, maxFiles, steps }: follow steps for each file, and the last step returns its url, to send the person or pass to create_product, create_asset or main_character. A picture or video of theirs goes through upload_file, a website through upload_site.","parameters":[],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"maxFiles":{"type":"integer","minimum":1,"maximum":10,"description":"How many files you will send, 1 to 10. Default 1."}},"additionalProperties":false}}}}}},"/v1/workspaces":{"get":{"operationId":"list_workspaces","summary":"List workspaces","description":"List every workspace the key's owner belongs to, newest first. Use it when they ask which workspaces they have or which one they are in. Returns data (id, name, role: admin or member, current); current is true for the one this key works in, the only one it reads and makes things in.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"create_workspace","summary":"Create workspace","description":"Make a new workspace with the key's owner as its admin. Use it when they ask for a new workspace, or a separate one for another brand or a client. Free; it starts with no credits. 10 per person at most, 5 an hour. Returns id and name. This key keeps working in its own workspace: to make things in the new one, open it in the app and make a key there in Settings, API and MCP.","parameters":[],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Workspace name."}},"required":["name"],"additionalProperties":false}}}}}}}}