{"openapi":"3.0.1","info":{"version":"v2beta","title":"StabilityAI REST API","description":"Welcome to the Stability Platform API. As of March 2024, we are building the REST v2beta API service to be the primary API service for the Stability Platform.\nAll AI services on other APIs (gRPC, REST v1, RESTv2alpha) will continue to be maintained, however they will not receive\nnew features or parameters.\n\nIf you are a REST v2alpha user, we strongly recommend that you adjust the URL calls for the specific services that you are using over to the equivalent REST v2beta URL. Normally, this means simply replacing \"v2alpha\" with \"v2beta\". We are not deprecating v2alpha URLs at this time for users that are currently using them.\n\n#### Authentication\n\nYou will need your [Stability API key](https://platform.stability.ai/account/keys) in order to make requests to this API.\nMake sure you never share your API key with anyone, and you never commit it to a public repository. Include this key in\nthe `Authorization` header of your requests.\n\n#### Rate limiting\n\nThis API is rate-limited to 150 requests every 10 seconds. If you exceed this limit, you will receive a `429` response\nand be timed out for 60 seconds. If you find this limit too restrictive, please reach out to us via [this form](https://kb.stability.ai/knowledge-base/kb-tickets/new).\n\n#### Support\n\nPlease see our [FAQ](https://platform.stability.ai/faq) for answers to common questions. If you have any other questions or concerns,\nplease reach out to us via [this form](https://kb.stability.ai/knowledge-base/kb-tickets/new).\n\nTo see the health of our APIs, please check our [Status Page](https://stabilityai.instatus.com/)."},"servers":[{"url":"https://api.stability.ai"}],"security":[{"STABILITY_API_KEY":[]}],"tags":[{"name":"Edit","description":"Tools for editing your own and generated images.\n\n**[Erase](/docs/api-reference#tag/Edit/paths/~1v2beta~1stable-image~1edit~1erase/post)**\n\nThe Erase service removes unwanted objects, such as blemishes on portraits or items on desks, using image masks.\n\n**[Outpaint](/docs/api-reference#tag/Edit/paths/~1v2beta~1stable-image~1edit~1outpaint/post)**\n\nThe outpaint service inserts additional content in an image to fill in the space in any direction, allowing you to \"zoom-out\" of an image.\n\n**[Inpaint](/docs/api-reference#tag/Edit/paths/~1v2beta~1stable-image~1edit~1inpaint/post)**\n\nThe Inpaint service modifies images by filling in or replacing specified areas with new content based on the content of a \"mask\" image.\n\n**[Search and Replace](/docs/api-reference#tag/Edit/paths/~1v2beta~1stable-image~1edit~1search-and-replace/post)**\n\nThe Search and Replace service, similar to inpaint, allows to replace specified areas with new content, but this time with the help of a prompt instead of a mask. The service will automatically segment the object and replace it with the object requested in the prompt.\n\n**[Search and Recolor](/docs/api-reference#tag/Edit/paths/~1v2beta~1stable-image~1edit~1search-and-recolor/post)**\n\nThe Search and Recolor service is another derivative of the inpaint service and provides the ability to change the color of a specific object in an image using a prompt. The Search and Recolor service will automatically segment the object and recolor it using the colors requested in the prompt.\n\n**[Remove Background](/docs/api-reference#tag/Edit/paths/~1v2beta~1stable-image~1edit~1remove-background/post)**\n\nThe Remove Background service accurately segments the foreground from an image to removes the background."},{"name":"Upscale","description":"Tools for increasing the size and resolution of your existing images.\n\n**[Fast Upscaler](/docs/api-reference#tag/Upscale/paths/~1v2beta~1stable-image~1upscale~1fast/post)**\n\nThis service enhances image resolution by 4x using predictive and generative AI. This lightweight and fast service (processing in ~1 second) is ideal for enhancing the quality of compressed images, making it suitable for social media posts and other applications.\n\n**[Conservative Upscaler](/docs/api-reference#tag/Upscale/paths/~1v2beta~1stable-image~1upscale~1conservative/post)**\n\nThis service can upscale images by 20 to 40 times up to a 4 megapixel output image with minimal alteration to the original image. The Conservative Upscaler can upscale images as small as 64x64 pixels directly to a 4 megapixel output. Use this option if you directly need a 4 megapixel output.\n\n**[Creative Upscaler](/docs/api-reference#tag/Upscale/paths/~1v2beta~1stable-image~1upscale~1creative/post)**\n\nThe service can upscale highly degraded images (lower than 1 megapixel) with a creative twist to provide high resolution results."},{"name":"Generate","description":"Tools to generate new images from text, or create variations of existing images. Our different services include:\n\n**[Stable Image Ultra](/docs/api-reference#tag/Generate/paths/~1v2beta~1stable-image~1generate~1ultra/post)**: Photorealistic, Large-Scale Output\n\nOur state of the art text to image model based on Stable Diffusion 3.5. Stable Image Ultra Produces the highest quality, photorealistic outputs perfect for professional print media and large format applications. Stable Image Ultra excels at rendering exceptional detail and realism.\n\n**[Stable Image Core](/docs/api-reference#tag/Generate/paths/~1v2beta~1stable-image~1generate~1core/post)**: Fast and Affordable\n\nOptimized for fast and affordable image generation, great for rapidly iterating on concepts during ideation. Stable Image Core is the next generation model following Stable Diffusion XL.\n\n**[Stable Diffusion 3.5 Model Suite](/docs/api-reference#tag/Generate/paths/~1v2beta~1stable-image~1generate~1sd3/post)**: Stability AI's latest base models\n\nThe different versions of our open models are available via API, letting you test and adjust speed and quality based on your use case. All model versions strike a balance between generation speed and output quality and are ideal for creating high-volume, high-quality digital assets like websites, newsletters, and marketing materials."},{"name":"Control","description":"Tools for generating precise, controlled variations of existing images or sketches.\n\n**[Sketch](/docs/api-reference#tag/Control/paths/~1v2beta~1stable-image~1control~1sketch/post)**\n\nThis service upgrades sketches to refined outputs with precise control. For non-sketch images, it allows detailed manipulation of the final appearance by leveraging the contour lines and edges within the image.\n\n**[Structure](/docs/api-reference#tag/Control/paths/~1v2beta~1stable-image~1control~1structure/post)**\n\nThis service excels in generating images by maintaining the structure of an input image, making it especially valuable for advanced content creation scenarios such as recreating scenes or rendering characters from models.\n\n**[Style](/docs/api-reference#tag/Control/paths/~1v2beta~1stable-image~1control~1style/post)**\n\nThis service extracts stylistic elements from an input image (control image) and uses it to guide the creation of an output image based on the prompt. The result is a new image in the same style as the control image."},{"name":"Results","description":"Tools for fetching the results of your async generations."},{"name":"Stable Audio 2","description":"Tools to generate music and sound from text or audio, or transform existing audio clips into new compositions. Our different services include:\n\n**Stable Audio 2.5**: Fast, Best-Quality, Long-Form Music & Audio Generation\n\nOur most advanced audio generation model, capable of generating up to 3-minute, 44.1 kHz stereo compositions. Stable Audio 2.5 supports text-to-audio, audio-to-audio, and audio-inpaint workflows - allowing creators to upload a sound and transform it into new instruments, styles, or genres using natural language prompts. Ideal for music production, cinematic sound design, and remixing.\n\n**Stable Audio 2.0**: High-Quality Audio Generation\n\nBuilt for text-to-audio and audio-to-audio generation, also capable of generating up to 3-minute, 44.1 kHz stereo. Stable Audio 2.0 is great for ideation, music demos, and ambient soundscapes. It's optimized for creative professionals seeking detailed and extended outputs from simple prompts.\n\nStable Audio models were exclusively trained on licensed data from the [AudioSparx](https://www.audiosparx.com/) music library, honoring opt-out requests and ensuring fair compensation for creators. Additionally, Stable Audio 2.5 was pre-trained on licensed data from [Freesound](https://freesound.org/). Read more about the model capabilities [here](https://stability.ai/news/stable-audio-2-0).","x-displayName":"Stable Audio 2.5"},{"name":"Stable Audio","description":"Tools to generate music and sound from text or audio, or transform existing audio clips into new compositions. Our different services include:\n\n**Stable Audio 3.0**: Fast, Best-Quality, Long-Form Music & Audio Generation\n\nOur most advanced audio generation model, capable of generating up to 6-minute, 44.1 kHz stereo compositions. Stable Audio 3.0 supports text-to-audio, audio-to-audio, and audio-inpaint workflows - allowing creators to upload a sound and transform it into new instruments, styles, or genres using natural language prompts. Ideal for music production, cinematic sound design, and remixing.\n\nStable Audio models were exclusively trained on licensed data from the [AudioSparx](https://www.audiosparx.com/) music library, honoring opt-out requests and ensuring fair compensation for creators. Additionally, Stable Audio 3.0 was pre-trained on licensed data from [Freesound](https://freesound.org/). Read more about the model capabilities [here](https://stability.ai/news/stable-audio-3-0).","x-displayName":"Stable Audio 3.0"}],"x-tagGroups":[{"name":"Stable Image","tags":["Generate","Upscale","Edit","Control","Results"]},{"name":"Audio","tags":["Stable Audio 2","Stable Audio"]},{"name":"3D","tags":["3D"]}],"components":{"securitySchemes":{"STABILITY_API_KEY":{"type":"apiKey","scheme":"bearer","name":"authorization","in":"header","description":"Use your [Stability API key](https://platform.stability.ai/account/keys) to authentication requests to this App."}},"schemas":{"GenerationID":{"type":"string","minLength":64,"maxLength":64,"description":"The `id` of a generation, typically used for async generations, that can be used to check the status of the generation or retrieve the result.","example":"a6dc6c6e20acda010fe14d71f180658f2896ed9b4ec25aa99a6ff06c796987c4"},"ContentModerationResponse":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Our content moderation system has flagged some part of your request and subsequently denied it.  You were not charged for this request.  While this may at times be frustrating, it is necessary to maintain the integrity of our platform and ensure a safe experience for all users.\n\nIf you would like to provide feedback, please use the [Support Form](https://kb.stability.ai/knowledge-base/kb-tickets/new).","enum":["content_moderation"]},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"description":"Your request was flagged by our content moderation system.","example":{"id":"ed14db44362126aab3cbd25cca51ffe3","name":"content_moderation","errors":["Your request was flagged by our content moderation system, as a result your request was denied and you were not charged."]}},"InpaintingSearchModeRequestBody":{"type":"object","properties":{"mode":{"type":"string","enum":["search"],"description":"Controls how the model decides which areas to inpaint and which areas to leave alone.\n\nSpecifying `mask` requires:\n  - Provide an explicit mask image in the `mask` parameter\n  - Use the alpha channel of the `image` parameter as the mask\n\nSpecifying `search` requires:\n  - Provide a small description of what to inpaint in the `search_prompt` parameter"},"search_prompt":{"type":"string","description":"Short description of what to inpaint in the `image`.","example":"glasses"},"image":{"type":"string","description":"The image you wish to inpaint.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels","format":"binary","example":"./some/image.png"},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."}},"required":["image","prompt","mode","search_prompt"]},"InpaintingMaskingModeRequestBody":{"type":"object","properties":{"mode":{"type":"string","enum":["mask"],"description":"Controls how the model decides which areas to inpaint and which areas to leave alone.\n\nSpecifying `mask` requires:\n  - Provide an explicit mask image in the `mask` parameter\n  - Use the alpha channel of the `image` parameter as the mask\n\nSpecifying `search` requires:\n  - Provide a small description of what to inpaint in the `search_prompt` parameter"},"mask":{"type":"string","description":"Controls the strength of the inpainting process on a per-pixel basis, either via a\nsecond image (passed into this parameter) or via the alpha channel of the `image` parameter.\n\n**Passing in a Mask**\n\nThe image passed to this parameter should be a black and white image that represents,\nat any pixel, the strength of inpainting based on how dark or light the given pixel is.\nCompletely black pixels represent no inpainting strength while completely white pixels\nrepresent maximum strength.\n\nIn the event the mask is a different size than the `image` parameter, it will be automatically resized.\n\n**Alpha Channel Support**\n\nIf you don't provide an explicit mask, one will be derived from the alpha channel of the `image` parameter.\nTransparent pixels will be inpainted while opaque pixels will be preserved.\n\nIn the event an `image` with an alpha channel is provided along with a `mask`, the `mask` will take precedence.","format":"binary","example":"./some/image.png"},"image":{"type":"string","description":"The image you wish to inpaint.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels","format":"binary","example":"./some/image.png"},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."}},"required":["image","prompt","mode"]},"StabilityClientID":{"type":"string","maxLength":256,"description":"The name of your application, used to help us communicate app-specific debugging or moderation issues to you.","example":"my-awesome-app"},"StabilityClientUserID":{"type":"string","maxLength":256,"description":"A unique identifier for your end user. Used to help us communicate user-specific debugging or moderation issues to you. Feel free to obfuscate this value to protect user privacy.","example":"DiscordUser#9999"},"StabilityClientVersion":{"type":"string","maxLength":256,"description":"The version of your application, used to help us communicate version-specific debugging or moderation issues to you.","example":"1.2.1"},"Creativity":{"type":"number","minimum":0.2,"maximum":0.5,"default":0.35,"description":"Controls the likelihood of creating additional details not heavily conditioned by the init image."},"FalGenerationResponse":{"type":"object","properties":{"s3Url":{"type":"string","nullable":true,"description":"An S3 object URL in the form `s3://bucket/key` pointing to the generated asset.\nInternal callers can fetch this object from S3 to download the bytes. `null` when\nthe output was withheld (e.g. it failed content moderation — see the `finish-reason` header).","example":"s3://stabilityapi-outputs-123456789012-us-west-2/fal/engine/output-id"},"contentType":{"type":"string","description":"The MIME type of the generated asset.","example":"image/png"}},"required":["s3Url","contentType"]}},"parameters":{}},"paths":{"/v2alpha/generation/stable-image/upscale":{"post":{"tags":["v2alpha/generation"],"summary":"stable-image/upscale","description":"Takes images between 64x64 and 1 megapixel and upscales them all the way to **4K** resolution.  Put more\ngenerally, it can upscale images ~20-40x times while preserving, and often enhancing, quality.\n\n### How to use\n  - Invoke this endpoint with the required parameters to start a generation\n  - Use that `id` in the response to poll for results at the [upscale/result/{id}](#tag/v2alphageneration/paths/~1v2alpha~1generation~1stable-image~1upscale~1result~1%7Bid%7D/get) endpoint\n    - Rate-limiting or other errors may occur if you poll more than once every 10 seconds\n\n### Price\nFlat rate of 25 cents per generation.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2alpha/generation/stable-image/upscale\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\"\n    },\n    files={\n        \"image\": open(\"./kitten-in-space.png\", \"rb\")\n    },\n    data={\n        \"prompt\": \"cute fluffy white kitten floating in space, pastel colors\",\n        \"output_format\": \"webp\",\n    },\n)\n\nprint(\"Generation ID:\", response.json().get('id'))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst formData = {\n  image: fs.createReadStream(\"./kitten-in-space.png\"),\n  prompt: \"cute fluffy white kitten floating in space, pastel colors\",\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2alpha/generation/stable-image/upscale`,\n  axios.toFormData(formData, new FormData()),\n  {\n    validateStatus: undefined,\n    headers: { Authorization: `Bearer sk-MYAPIKEY` },\n  },\n);\n\nconsole.log(\"Generation ID:\", response.data.id);"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2alpha/generation/stable-image/upscale\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -F image=@\"./kitten-in-rainforest.png\" \\\n  -F prompt=\"cute fluffy white kitten sitting in a rainforest, pastel colors\" \\\n  -F output_format=webp \\\n  -o \"./output.json\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image you wish to upscale.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 1,048,576 pixels","format":"binary","example":"./some/image.png"},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"creativity":{"type":"number","minimum":0.1,"maximum":0.5,"default":0.3,"description":"Indicates how creative the model should be when upscaling an image.\nHigher values will result in more details being added to the image during upscaling."},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."}},"required":["image","prompt"]}}}},"responses":{"200":{"description":"Upscaling was successful!","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/GenerationID"}},"required":["id"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2alpha/generation/stable-image/upscale/result/{id}":{"get":{"tags":["v2alpha/generation"],"summary":"stable-image/upscale/result","description":"Fetch the result of an upscale generation by ID. Make sure to use the same API key to fetch the generation result\nthat you used to create the generation, otherwise you will receive a `404` response.\n\n### How is progress reported?\nYour generation is either `in-progress` (i.e. status code `202`) or it is complete (i.e. status code `200`). \nWe may add more fine-grained progress reporting in the future (e.g. a numerical progress).\n\n### How long are results stored?\nResults are stored for 24 hours after generation. After that, the results are deleted.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\ngeneration_id = \"e52772ac75b...\"\n\nresponse = requests.request(\n    \"GET\",\n    f\"https://api.stability.ai/v2alpha/generation/stable-image/upscale/result/{generation_id}\",\n    headers={\n        'Accept': \"image/*\",  # Use 'application/json' to receive base64 encoded JSON\n        'authorization': f\"Bearer sk-MYAPIKEY\"\n    },\n)\n\nif response.status_code == 202:\n    print(\"Generation in-progress, try again in 10 seconds.\")\nelif response.status_code == 200:\n    print(\"Generation complete!\")\n    with open(\"upscaled.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import axios from \"axios\";\nimport fs from \"node:fs\";\n\nconst generationID = \"e52772ac75b...\";\n\nconst response = await axios.request({\n  url: `https://api.stability.ai/v2alpha/generation/stable-image/upscale/result/${generationID}`,\n  method: \"GET\",\n  validateStatus: undefined,\n  responseType: \"arraybuffer\",\n  headers: {\n    accept: \"image/*\", // Use 'application/json' to receive base64 encoded JSON\n    authorization: `Bearer sk-MYAPIKEY`,\n  },\n});\n\nif (response.status === 202) {\n  console.log(\"Generation is still running, try again in 10 seconds.\");\n} else if (response.status === 200) {\n  console.log(\"Generation is complete!\");\n  fs.writeFileSync(\"upscaled.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`Response ${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"generation_id=\"e52772ac75b...\"\nurl=\"https://api.stability.ai/v2alpha/generation/stable-image/upscale/result/$generation_id\"\nhttp_status=$(curl -sS -f -o \"./upscaled.webp\" -w '%{http_code}' -H \"authorization: sk-MYAPIKEY\" -H 'accept: image/*' \"$url\")\n\ncase $http_status in\n    202)\n        echo \"Still processing. Retrying in 10 seconds...\"\n        ;;\n    200)\n        echo \"Download complete!\"\n        ;;\n    4*|5*)\n        mv \"./upscaled.webp\" \"./error.json\"\n        echo \"Error: Check ./error.json for details.\"\n        exit 1\n        ;;\nesac"}],"parameters":[{"schema":{"$ref":"#/components/schemas/GenerationID"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to get the image bytes directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"}],"responses":{"200":{"description":"The upscale was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"202":{"description":"Your upscale generation is still in-progress.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/GenerationID"},"status":{"type":"string","enum":["in-progress"],"description":"The status of your generation."}},"required":["id","status"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"404":{"description":"id: the generation either does not exist or has expired.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2bca35116bc5431d6dc4b4ea2ef3da2f","name":"generation_not_found","errors":["id: the generation either does not exist or has expired."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2alpha/generation/stable-image/inpaint":{"post":{"tags":["v2alpha/generation"],"summary":"stable-image/inpaint","description":"Inpaint an existing image, with or without a mask, using our latest-and-greatest inpainting model.\n\n### Search-and-Replace Mode\nThis mode is ideal for individuals of all levels of skill in design. It can be used for straightforward\nadjustments to images. The service will automatically mask the most appropriate object based on the contents\nof the `search_prompt`, and replace it with a generated result based on the `prompt`.\n\n**How to use:** set the `mode` parameter to `search` and provide a short description of what to\nsearch-and-replace in the `search_prompt` parameter.\n\n### Mask Mode\nThis mode allows for precise control of generative fill tasks on an image, down to the level of\nindividual pixels. Design professionals can provide a `mask` for the section of the image to be replaced,\nand use standard image prompting to describe the full image as it should appear after the editing.\nThe resulting image will incorporate all of the elements described in the `prompt`.\n\n**How to use:** set the `mode` parameter to `mask` and either pass in an `image` with an alpha channel\nor provide an explicit mask image to the `mask` parameter. If both are present the `mask` parameter will\ntake precedence.\n\n### Price\n- Requests with `mode` set to `search` cost 4 cents.\n- Requests with `mode` set to `mask` cost 3 cents.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2alpha/generation/stable-image/inpaint\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\"\n    },\n    files={\n        \"image\": open(\"./husky-in-a-field.png\", \"rb\")\n    },\n    data={\n        \"prompt\": \"golden retriever in a field\",\n        \"mode\": \"search\",\n        \"search_prompt\": \"dog\",\n        \"output_format\": \"webp\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./golden-retriever-in-a-field.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst formData = {\n  image: fs.createReadStream(\"./husky-in-a-field.png\"),\n  prompt: \"golden retriever standing in a field\",\n  mode: \"search\",\n  search_prompt: \"dog\",\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2alpha/generation/stable-image/inpaint`,\n  axios.toFormData(formData, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { Authorization: `Bearer sk-MYAPIKEY`, accept: \"image/*\" },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./golden-retriever-in-a-field.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2alpha/generation/stable-image/inpaint\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./husky-in-a-field.png\" \\\n  -F prompt=\"golden retriever in a field\" \\\n  -F mode=\"search\" \\\n  -F search_prompt=\"dog\" \\\n  -F output_format=\"webp\" \\\n  -o \"./golden-retriever-in-a-field.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to get the image bytes directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"oneOf":[{"$ref":"#/components/schemas/InpaintingSearchModeRequestBody"},{"$ref":"#/components/schemas/InpaintingMaskingModeRequestBody"}],"discriminator":{"propertyName":"mode","mapping":{"search":"#/components/schemas/InpaintingSearchModeRequestBody","mask":"#/components/schemas/InpaintingMaskingModeRequestBody"}}}}}},"responses":{"200":{"description":"Inpainting was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/3d/stable-fast-3d":{"post":{"tags":["3D"],"summary":"Stable Fast 3D","description":"Stable Fast 3D generates high-quality 3D assets from a single 2D input image.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_3D_API.ipynb)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`.\n\nThe body of the request should include:\n- `image`\n\nThe body may optionally include:\n- `texture_resolution`\n- `foreground_ratio`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe output is a binary blob that includes a glTF asset, including JSON, buffers, and images.\nSee the [GLB File Format Specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#glb-file-format-specification) for more details.\n\n### Credits\nFlat rate of 10 credits per successful generation. You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/3d/stable-fast-3d\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n    },\n    files={\n        \"image\": open(\"./cat-statue.png\", \"rb\")\n    },\n    data={},\n)\n\nif response.status_code == 200:\n    with open(\"./3d-cat-statue.glb\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import axios from \"axios\";\nimport FormData from \"form-data\";\nimport fs from \"node:fs\";\n\nconst payload = {\n    image: fs.createReadStream(\"./cat-statue.png\"),\n};\n\nconst response = await axios.postForm(\n    `https://api.stability.ai/v2beta/3d/stable-fast-3d`,\n    axios.toFormData(payload, new FormData()),\n    {\n        validateStatus: undefined,\n        responseType: \"arraybuffer\",\n        headers: {\n            Authorization: `Bearer sk-MYAPIKEY`,\n        },\n    },\n);\n\nif (response.status === 200) {\n    fs.writeFileSync(\"./3d-cat-statue.glb\", Buffer.from(response.data));\n} else {\n    throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/3d/stable-fast-3d\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -F image=@\"./cat-statue.png\" \\\n  -o \"./3d-cat-statue.glb\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image to generate a 3D model from.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 4,194,304 pixels","format":"binary","example":"./some/image.png"},"texture_resolution":{"type":"string","enum":["512","1024","2048"],"default":"1024","description":"Determines the resolution of the textures used for both the albedo (color) map\nand the normal map. The resolution is specified in pixels, and a higher value\ncorresponds to a higher level of detail in the textures, allowing for more\nintricate and precise rendering of surfaces. However, increasing the resolution\nalso results in larger asset sizes, which may impact loading times and\nperformance. 1024 is a good default value and rarely requires changing."},"foreground_ratio":{"type":"number","minimum":0.1,"maximum":1,"default":0.85,"description":"Controls the amount of padding around the object to be processed within the frame.\nThis ratio determines the relative size of the object compared to the total frame\nsize. A higher ratio means less padding and a larger object, while a lower ratio\nincreases the padding, effectively reducing the object’s size within the frame. This\ncan be useful when a long and narrow object, such as a car or bus, is viewed from the\nfront (the narrow side). Here, lowering the foreground ratio might help prevent the\ngenerated 3D assets from appearing squished or distorted. The default value of 0.85\nis good for most objects."},"remesh":{"type":"string","enum":["none","triangle","quad"],"default":"none","description":"Controls the remeshing algorithm used to generate the 3D model. The remeshing\nalgorithm determines how the 3D model is constructed from the input image. The\ndefault value of \"none\" means that the model is generated without remeshing,\nwhich is suitable for most use cases. The \"triangle\" option generates a model\nwith triangular faces, while the \"quad\" option generates a model with quadrilateral\nfaces. The \"quad\" option is useful when the 3D model will be used in DCC tools such\nas Maya or Blender."},"vertex_count":{"type":"number","minimum":-1,"maximum":20000,"default":-1,"description":"If specified, the result will have approximately this many vertices (and consequently fewer faces) in the simplified mesh.\n\nSetting this value to -1 (the default value) means that a limit is not set."}},"required":["image"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"content-type":{"description":"The format of the 3D model.","schema":{"type":"string","example":"model/gltf-binary"}}},"content":{"model/gltf-binary":{"schema":{"type":"string","description":"The bytes of the generated 3D model.","format":"binary"}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/3d/stable-point-aware-3d":{"post":{"tags":["3D"],"summary":"Stable Point Aware 3D","description":"Stable Point Aware 3D (SPAR3D) can make real-time edits and create the complete structure\nof a 3D object from a single image in a few seconds. SPAR3D combines the strengths of\npoint-cloud diffusion (probabilistic) and mesh regression (deterministic) to have improved\ndetails on the unseen back regions in the input image.\n\nCompared to our previous model [Stable Fast 3D](#tag/3D/paths/~1v2beta~13d~1stable-fast-3d/post), this new\none allows editing of backside information using the point cloud representation and also\nleverages a larger Diffusion model to generally improve the depth and backside\npredictions.\n\nRead more about the model capabilities [here](https://bit.ly/4h7cpgF).\n\nThis API is currently in\npreview. Please don’t hesitate to [contact us](https://stability.ai/contact) with any questions.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_3D_API.ipynb)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`.\n\nThe body of the request should include:\n- `image`\n\nThe body may optionally include:\n- `texture_resolution`\n- `foreground_ratio`\n- `remesh`\n- `target_type`\n- `target_count`\n- `guidance_scale`\n- `seed`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe output is a binary blob that includes a glTF asset, including JSON, buffers, and images.\nSee the [GLB File Format Specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#glb-file-format-specification) for more details.\n\n### Credits\nFlat rate of 4 credits per successful generation. You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/3d/stable-point-aware-3d\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n    },\n    files={\n        \"image\": open(\"./cat-statue.png\", \"rb\")\n    },\n    data={},\n)\n\nif response.status_code == 200:\n    with open(\"./3d-cat-statue.glb\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import axios from \"axios\";\nimport FormData from \"form-data\";\nimport fs from \"node:fs\";\n\nconst payload = {\n    image: fs.createReadStream(\"./cat-statue.png\"),\n};\n\nconst response = await axios.postForm(\n    `https://api.stability.ai/v2beta/3d/stable-point-aware-3d`,\n    axios.toFormData(payload, new FormData()),\n    {\n        validateStatus: undefined,\n        responseType: \"arraybuffer\",\n        headers: {\n            Authorization: `Bearer sk-MYAPIKEY`,\n        },\n    },\n);\n\nif (response.status === 200) {\n    fs.writeFileSync(\"./3d-cat-statue.glb\", Buffer.from(response.data));\n} else {\n    throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/3d/stable-point-aware-3d\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -F image=@\"./cat-statue.png\" \\\n  -o \"./3d-cat-statue.glb\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image to generate a 3D model from.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 4,194,304 pixels","format":"binary","example":"./some/image.png"},"texture_resolution":{"type":"string","enum":["512","1024","2048"],"default":"1024","description":"Determines the resolution of the textures used for both the albedo (color) map and the\nnormal map. The resolution is specified in pixels, and a higher value corresponds to a\nhigher level of detail in the textures, allowing for more intricate and precise rendering\nof surfaces. However, increasing the resolution also results in larger asset sizes, which\nmay impact loading times and performance. `1024` is a good default value and rarely requires\nchanging."},"foreground_ratio":{"type":"number","minimum":1,"maximum":2,"default":1.3,"description":"Controls the amount of padding around the object to be processed within the frame. This\nratio determines the relative size of the object compared to the total frame size. A\nhigher ratio means less padding and a larger object, while a lower ratio increases the\npadding, effectively reducing the object’s size within the frame. This can be useful when\na long and narrow object, such as a car or bus, is viewed from the front (the narrow\nside). Here, lowering the foreground ratio might help prevent the generated 3D assets from\nappearing squished or distorted. The default value of `1.3` is good for most objects."},"remesh":{"type":"string","enum":["none","triangle","quad"],"default":"none","description":"Controls the remeshing algorithm used to generate the 3D model. The remeshing algorithm\ndetermines how the 3D model is constructed from the input image. The default value of\n\"none\" means that the model is generated without remeshing, which is suitable for most use\ncases. The \"triangle\" option generates a model with triangular faces, while the \"quad\"\noption generates a model with quadrilateral faces. The \"quad\" option is useful when the 3D\nmodel will be used in DCC tools such as Maya or Blender."},"target_type":{"type":"string","enum":["none","vertex","face"],"default":"none","description":"If set to `vertex` or `face`, the result will have approximately `target_count` many vertices or\nfaces in the simplified mesh, respectively."},"target_count":{"type":"number","minimum":100,"maximum":20000,"default":1000,"description":"This sets the target vertex or face count defined by `target_type`. Selecting extremely low\ncounts reduces the quality of the mesh severely and values of 1,000 - 10,000 are recommended."},"guidance_scale":{"type":"number","minimum":1,"maximum":10,"default":3,"description":"This sets the guidance scaling of the point diffusion module. Lower values produce less\ndetail and higher can introduce artifacts. The default of `3` produces best results."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"}},"required":["image"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"content-type":{"description":"The format of the 3D model.","schema":{"type":"string","example":"model/gltf-binary"}}},"content":{"model/gltf-binary":{"schema":{"type":"string","description":"The bytes of the generated 3D model.","format":"binary"}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/results/{id}":{"get":{"tags":["Results"],"summary":"Fetch async generation result","description":"Fetch the result of a generation by ID.\n\nMake sure to use the same API key to fetch the generation result that you used to create the generation,\notherwise you will receive a `404` response.\n\n### How to use\nPlease invoke this endpoint with a `GET` request.\n\nThe headers of the request must include an API key in the `authorization` field and the ID\nof your generation must be in the path.\n\n### How is progress reported?\nYour generation is either `in-progress` (i.e. status code `202`) or it is complete (i.e. status code `200`).\nWe may add more fine-grained progress reporting in the future (e.g. a numerical progress).\n\n### How long are results stored?\nResults are stored for 24 hours after generation. After that, the results are deleted.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\ngeneration_id = \"e52772ac75b...\"\n\nresponse = requests.request(\n    \"GET\",\n    f\"https://api.stability.ai/v2beta/results/{generation_id}\",\n    headers={\n        'accept': \"image/*\",  # Use 'application/json' to receive base64 encoded JSON\n        'authorization': f\"Bearer sk-MYAPIKEY\"\n    },\n)\n\nif response.status_code == 202:\n    print(\"Generation in-progress, try again in 10 seconds.\")\nelif response.status_code == 200:\n    print(\"Generation complete!\")\n    with open(\"result.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import axios from \"axios\";\nimport fs from \"node:fs\";\n\nconst generationID = \"e52772ac75b...\";\n\nconst response = await axios.request({\n  url: `https://api.stability.ai/v2beta/results/${generationID}`,\n  method: \"GET\",\n  validateStatus: undefined,\n  responseType: \"arraybuffer\",\n  headers: {\n    Authorization: `Bearer sk-MYAPIKEY`,\n    Accept: \"image/*\", // Use 'application/json' to receive base64 encoded JSON\n  },\n});\n\nif (response.status === 202) {\n  console.log(\"Generation is still running, try again in 10 seconds.\");\n} else if (response.status === 200) {\n  console.log(\"Generation is complete!\");\n  fs.writeFileSync(\"result.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`Response ${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"generation_id=\"e52772ac75b...\"\nurl=\"https://api.stability.ai/v2beta/results/$generation_id\"\nhttp_status=$(curl -sS -f -o \"./result.webp\" -w '%{http_code}' -H \"authorization: sk-MYAPIKEY\" -H 'accept: image/*' \"$url\")\n\ncase $http_status in\n    202)\n        echo \"Still processing. Retrying in 10 seconds...\"\n        ;;\n    200)\n        echo \"Download complete!\"\n        ;;\n    4*|5*)\n        mv \"./result.webp\" \"./error.json\"\n        echo \"Error: Check ./error.json for details.\"\n        exit 1\n        ;;\nesac"}],"parameters":[{"schema":{"$ref":"#/components/schemas/GenerationID"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","default":"*/*","description":"Specify `*/*` to receive the bytes of the result directly. Otherwise specify `application/json` to receive the result as base64 encoded JSON.","enum":["*/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"responses":{"200":{"description":"Generation finished.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"202":{"description":"Your generation is still in-progress.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/GenerationID"},"status":{"type":"string","enum":["in-progress"],"description":"The status of your generation."}},"required":["id","status"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"404":{"description":"id: the generation either does not exist or has expired.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2bca35116bc5431d6dc4b4ea2ef3da2f","name":"generation_not_found","errors":["id: the generation either does not exist or has expired."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/audio/stable-audio-2/text-to-audio":{"post":{"tags":["Stable Audio 2"],"summary":"Text-to-Audio","description":"Stable Audio generates high-quality music and sound effects up to three minutes long at\n44.1kHz stereo from text descriptions. Learn how to craft effective prompts in our\n[Prompt Guide](https://www.stableaudio.com/user-guide/text-to-audio) to get the best results\nfrom your generations.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to\n[![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Audio_API.ipynb)\nor try Stable Audio 2.0 for free at [stableaudio.com](https://stableaudio.com).\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`. The `accept` header should be set to one of the following:\n- `audio/*` to receive the audio in the format specified by the `output_format` parameter.\n- `application/json` to receive the audio encoded as base64 in a JSON response.\n\nThe body of the request should include:\n- `prompt` - text to generate the audio from. Check our\n[prompt guide](https://www.stableaudio.com/user-guide/text-to-audio) for tips\n\n#### **Optional Parameters:**\nThe body may optionally include:\n- `output_format` - the format of the output audio\n- `seed` - the randomness seed to use for the generation\n- `steps` - the number of sampling steps\n- `duration` - the number of seconds of the generated audio\n- `cfg_scale` - controls how strictly the diffusion process adheres to the prompt text (only for `stable-audio-2`)\n- `model` - the model to use [`stable-audio-2`, `stable-audio-2.5`]\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Credits\n\n**Stable Audio 2.0**\n\nBy default, 20 credits per successful generation. The number of credits is determined\nby the following formula: `credits = 17 + 0.06 * steps`.\n\nExamples:\n- 50 steps = 20 credits [default]\n- 100 steps = 23 credits\n\n**Stable Audio 2.5**\n\nRequests made using the Stable Audio 2.5 model have a flat rate of 20 credits per successful result.\n\nAs always, you will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/audio/stable-audio-2/text-to-audio\",\n    headers={\"authorization\": f\"Bearer sk-MYAPIKEY\", \"accept\": \"audio/*\"},\n    files={\"none\": \"\"},\n    data={\n        \"prompt\": \"A song in the 3/4 time signature that features cheerful acoustic guitar, live recorded drums, and rhythmic claps, The mood is happy and up-lifting.\",\n        \"output_format\": \"mp3\",\n        \"duration\": 20,\n        \"model\": \"stable-audio-2.5\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./output.mp3\", \"wb\") as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  prompt:\n    \"A song in the 3/4 time signature that features cheerful acoustic guitar, live recorded drums, and rhythmic claps, The mood is happy and up-lifting.\",\n  output_format: \"mp3\",\n  duration: 20,\n  model: \"stable-audio-2.5\",\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/audio/stable-audio-2/text-to-audio`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: {\n      Authorization: `Bearer sk-MYAPIKEY`,\n      Accept: \"audio/*\",\n    },\n  }\n);\n\nif (response.status === 200) {\n  fs.writeFileSync(\"./output.mp3\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/audio/stable-audio-2/text-to-audio\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: audio/*\" \\\n  -F prompt=\"A song in the 3/4 time signature that features cheerful acoustic guitar, live recorded drums, and rhythmic claps, The mood is happy and up-lifting.\" \\\n  -F output_format=\"mp3\" \\\n  -F duration=\"20\" \\\n  -F model=\"stable-audio-2.5\" \\\n  -o \"./uk-bass.mp3\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"audio/*","description":"Specify `audio/*` to receive the bytes of the audio directly. Otherwise specify `application/json` to receive the audio as base64 encoded JSON.","enum":["audio/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"description":"What you wish the output audio to be. A strong, descriptive prompt that clearly defines\ninstruments, moods, styles, and genre will lead to better results.\n\nYou can make a prompt as simple or complex as you like. Simple prompts are good for clean\noutput audio. Complex prompts are good for adding texture and depth to the output audio.\n\n\nCheck our [prompt guide](https://www.stableaudio.com/user-guide/text-to-audio) for tips."},"duration":{"type":"number","minimum":1,"maximum":190,"default":190,"description":"Controls the duration in seconds of the generated audio."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"steps":{"type":"integer","description":"Controls the number of sampling steps.\n\n- For `stable-audio-2`: accepts steps between `30` and `100` (defaults to `50`).\n- For `stable-audio-2.5`: accepts steps between `4` and `8` (defaults to `8`)."},"cfg_scale":{"type":"number","minimum":1,"maximum":25,"description":"How strictly the diffusion process adheres to the prompt text (higher values make your\naudio closer to your prompt). \n\nDefaults to 7 for `stable-audio-2` and 1 for `stable-audio-2.5` if not specified."},"model":{"type":"string","enum":["stable-audio-2.5","stable-audio-2"],"default":"stable-audio-2","description":"The model to use for generation.\n\n- `stable-audio-2.5` requires 20 credits per generation\n- `stable-audio-2` requires 20 credits per generation"},"output_format":{"type":"string","enum":["mp3","wav"],"default":"mp3","description":"Dictates the `content-type` of the generated audio."}},"required":["prompt"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated audio.\n\n To receive the bytes of the audio directly, specify `audio/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"mpeg":{"description":"raw bytes","value":"audio/mpeg"},"mpegJSON":{"description":"base64 encoded","value":"application/json; type=audio/mpeg"},"wav":{"description":"raw bytes","value":"audio/wav"},"wavJSON":{"description":"base64 encoded","value":"application/json; type=audio/wav"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS"]},"description":"Indicates the reason the generation finished. It is always `SUCCESS` for this endpoint.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"audio/mpeg":{"schema":{"type":"string","description":"The bytes of the generated audio.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated mpeg"},"application/json; type=audio/mpeg":{"schema":{"type":"object","properties":{"audio":{"type":"string","description":"The generated audio, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS"],"description":"The reason the generation finished. It is always `SUCCESS` for this endpoint.","example":"SUCCESS"}},"required":["audio","finish_reason"]}},"audio/wav":{"schema":{"type":"string","description":"The bytes of the generated audio.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated wav"},"application/json; type=audio/wav":{"schema":{"type":"object","properties":{"audio":{"type":"string","description":"The generated audio, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS"],"description":"The reason the generation finished. It is always `SUCCESS` for this endpoint.","example":"SUCCESS"}},"required":["audio","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Copyrighted Content Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"copyrighted_content","errors":["Our system has detected the presence of copyrighted content in your audio. To comply with our guidelines, we cannot process this request. Please upload a different audio file."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/audio/stable-audio-2/audio-to-audio":{"post":{"tags":["Stable Audio 2"],"summary":"Audio-to-Audio","description":"Stable Audio transforms existing audio samples into new high-quality compositions up to three minutes\nlong at 44.1kHz stereo using text instructions. Discover techniques for sample transformation in our\n[Audio to Audio Guide](https://www.stableaudio.com/user-guide/audio-to-audio) to maximize creative control.\nRead more about the model capabilities [here](https://stability.ai/news/stable-audio-2-0).\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to\n[![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Audio_API.ipynb)\nor try Stable Audio 2.0 for free at [stableaudio.com](https://stableaudio.com).\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`. The `accept` header should be set to one of the following:\n- `audio/*` to receive the audio in the format specified by the `output_format` parameter.\n- `application/json` to receive the audio encoded as base64 in a JSON response.\n\nThe body of the request should include:\n- `prompt` - text to generate the audio from. Check our\n[prompt guide](https://www.stableaudio.com/user-guide/audio-to-audio) for tips\n- `audio` - the audio to use as the starting point for the generation\n\n> **Notes:**\n> - We do not allow copyrighted content to be uploaded to our platform.\n> - Maximum request size is 50Mb.\n\n#### **Optional Parameters:**\nThe body may optionally include:\n- `output_format` - the format of the output audio\n- `seed` - the randomness seed to use for the generation\n- `steps` - the number of sampling steps\n- `duration` - the number of seconds of the generated audio\n- `cfg_scale` - controls how strictly the diffusion process adheres to the prompt text (only for `stable-audio-2`)\n- `model` - the model to use [`stable-audio-2`, `stable-audio-2.5`]\n- `strength` - controls how much influence the `audio` parameter has on the output audio\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Credits\n\n**Stable Audio 2.0**\n\nBy default, 20 credits per successful generation. The number of credits is determined\nby the following formula: `credits = 17 + 0.06 * steps`.\nExamples:\n- 50 steps = 20 credits [default]\n- 100 steps = 23 credits\n\n**Stable Audio 2.5**\n\nRequests made using the Stable Audio 2.5 model have a flat rate of 20 credits per successful result.\n\nAs always, you will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/audio/stable-audio-2/audio-to-audio\",\n    headers={\"authorization\": f\"Bearer sk-MYAPIKEY\", \"accept\": \"audio/*\"},\n    files={\n        \"audio\": open(\"./uk-bass-base.mp3\", \"rb\"),\n    },\n    data={\n        \"prompt\": \"A song in the 3/4 time signature that features cheerful acoustic guitar, live recorded drums, and rhythmic claps, The mood is happy and up-lifting.\",\n        \"output_format\": \"mp3\",\n        \"duration\": 20,\n        \"model\": \"stable-audio-2.5\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./output.mp3\", \"wb\") as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  prompt:\n    \"A song in the 3/4 time signature that features cheerful acoustic guitar, live recorded drums, and rhythmic claps, The mood is happy and up-lifting.\",\n  output_format: \"mp3\",\n  duration: 20,\n  audio: fs.createReadStream(\"./uk-bass-base.mp3\"),\n  model: \"stable-audio-2.5\",\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/audio/stable-audio-2/audio-to-audio`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: {\n      Authorization: `Bearer sk-MYAPIKEY`,\n      Accept: \"audio/*\",\n    },\n  }\n);\n\nif (response.status === 200) {\n  fs.writeFileSync(\"./output.mp3\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/audio/stable-audio-2/audio-to-audio\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: audio/*\" \\\n  -F prompt=\"A song in the 3/4 time signature that features cheerful acoustic guitar, live recorded drums, and rhythmic claps, The mood is happy and up-lifting.\" \\\n  -F output_format=\"mp3\" \\\n  -F duration=\"20\" \\\n  -F model=\"stable-audio-2.5\" \\\n  -F audio=@\"./uk-bass-base.mp3\" \\\n  -o \"./output.mp3\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"audio/*","description":"Specify `audio/*` to receive the bytes of the audio directly. Otherwise specify `application/json` to receive the audio as base64 encoded JSON.","enum":["audio/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"description":"What you wish the output audio to be. A strong, descriptive prompt that clearly defines\ninstruments, moods, styles, and genre will lead to better results.\n\nYou can make a prompt as simple or complex as you like. Simple prompts are good for clean\noutput audio. Complex prompts are good for adding texture and depth to the output audio.\n\n\nCheck our [prompt guide](https://www.stableaudio.com/user-guide/audio-to-audio) for tips."},"duration":{"type":"number","minimum":1,"maximum":190,"default":190,"description":"Controls the duration in seconds of the generated audio."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"steps":{"type":"integer","description":"Controls the number of sampling steps.\n\n- For `stable-audio-2`: accepts steps between `30` and `100` (defaults to `50`).\n- For `stable-audio-2.5`: accepts steps between `4` and `8` (defaults to `8`)."},"cfg_scale":{"type":"number","minimum":1,"maximum":25,"description":"How strictly the diffusion process adheres to the prompt text (higher values make your\naudio closer to your prompt). \n\nDefaults to 7 for `stable-audio-2` and 1 for `stable-audio-2.5` if not specified."},"model":{"type":"string","enum":["stable-audio-2.5","stable-audio-2"],"default":"stable-audio-2","description":"The model to use for generation.\n\n- `stable-audio-2.5` requires 20 credits per generation\n- `stable-audio-2` requires 20 credits per generation"},"output_format":{"type":"string","enum":["mp3","wav"],"default":"mp3","description":"Dictates the `content-type` of the generated audio."},"audio":{"type":"string","description":"The audio to be use as the starting point for the generation.\n\nSupported Formats:\n- mp3\n- wav\n\nValidation Rule:\n- Audio must be between 6 and 190 seconds long","format":"binary","example":"./some/audio.mp3"},"strength":{"type":"number","minimum":0,"maximum":1,"default":1,"description":"Sometimes referred to as _denoising_, this parameter controls how much influence the\n`audio` parameter has on the generated audio.\nA value of 0 would yield audio that is identical to the input.\nA value of 1 would be as if you passed in no audio at all.\n\nMinimum value for `stable-audio-2.5` is 0.01."}},"required":["prompt","audio"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated audio.\n\n To receive the bytes of the audio directly, specify `audio/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"mpeg":{"description":"raw bytes","value":"audio/mpeg"},"mpegJSON":{"description":"base64 encoded","value":"application/json; type=audio/mpeg"},"wav":{"description":"raw bytes","value":"audio/wav"},"wavJSON":{"description":"base64 encoded","value":"application/json; type=audio/wav"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS"]},"description":"Indicates the reason the generation finished. It is always `SUCCESS` for this endpoint.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"audio/mpeg":{"schema":{"type":"string","description":"The bytes of the generated audio.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated mpeg"},"application/json; type=audio/mpeg":{"schema":{"type":"object","properties":{"audio":{"type":"string","description":"The generated audio, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS"],"description":"The reason the generation finished. It is always `SUCCESS` for this endpoint.","example":"SUCCESS"}},"required":["audio","finish_reason"]}},"audio/wav":{"schema":{"type":"string","description":"The bytes of the generated audio.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated wav"},"application/json; type=audio/wav":{"schema":{"type":"object","properties":{"audio":{"type":"string","description":"The generated audio, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS"],"description":"The reason the generation finished. It is always `SUCCESS` for this endpoint.","example":"SUCCESS"}},"required":["audio","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Copyrighted Content Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"copyrighted_content","errors":["Our system has detected the presence of copyrighted content in your audio. To comply with our guidelines, we cannot process this request. Please upload a different audio file."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/audio/stable-audio-2/inpaint":{"post":{"tags":["Stable Audio 2"],"summary":"Inpaint","description":"Stable Audio 2.5 transforms existing audio samples into new high-quality compositions up to three minutes\nlong at 44.1kHz stereo using text instructions.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to\n[![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Audio_API.ipynb).\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`. The `accept` header should be set to one of the following:\n- `audio/*` to receive the audio in the format specified by the `output_format` parameter.\n- `application/json` to receive the audio encoded as base64 in a JSON response.\n\nThe body of the request should include:\n- `prompt` - text to generate the audio from\n- `audio` - the audio to use as the starting point for the generation\n\n> **Notes:**\n> - We do not allow copyrighted content to be uploaded to our platform.\n> - Maximum request size is 50Mb.\n\n#### **Optional Parameters:**\nThe body may optionally include:\n- `output_format` - the format of the output audio\n- `seed` - the randomness seed to use for the generation\n- `duration` - the number of seconds of the generated audio\n- `steps` - the number of sampling steps\n- `mask_start` - start time in seconds for the audio segment to be inpainted (e.g., 30.0 for 30.0 seconds)\n- `mask_end` - end time in seconds for the audio segment to be inpainted (e.g., 190.0 for 190.0 seconds)\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Credits\n**Stable Audio 2.5**\n\nFlat rate of 20 credits per successful generation.\n\nAs always, you will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/audio/stable-audio-2/inpaint\",\n    headers={\"authorization\": f\"Bearer sk-MYAPIKEY\", \"accept\": \"audio/*\"},\n    files={\n        \"audio\": open(\"./uk-bass-base.mp3\", \"rb\"),\n    },\n    data={\n        \"prompt\": \"A song in the 3/4 time signature that features cheerful acoustic guitar, live recorded drums, and rhythmic claps, The mood is happy and up-lifting.\",\n        \"output_format\": \"mp3\",\n        \"duration\": 20,\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./output.mp3\", \"wb\") as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  prompt:\n    \"A song in the 3/4 time signature that features cheerful acoustic guitar, live recorded drums, and rhythmic claps, The mood is happy and up-lifting.\",\n  output_format: \"mp3\",\n  duration: 20,\n  audio: fs.createReadStream(\"./uk-bass-base.mp3\"),\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/audio/stable-audio-2/inpaint`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: {\n      Authorization: `Bearer sk-MYAPIKEY`,\n      Accept: \"audio/*\",\n    },\n  }\n);\n\nif (response.status === 200) {\n  fs.writeFileSync(\"./output.mp3\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/audio/stable-audio-2/inpaint\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: audio/*\" \\\n  -F prompt=\"A song in the 3/4 time signature that features cheerful acoustic guitar, live recorded drums, and rhythmic claps, The mood is happy and up-lifting.\" \\\n  -F output_format=\"mp3\" \\\n  -F duration=\"20\" \\\n  -F audio=@\"./uk-bass-base.mp3\" \\\n  -o \"./output.mp3\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"audio/*","description":"Specify `audio/*` to receive the bytes of the audio directly. Otherwise specify `application/json` to receive the audio as base64 encoded JSON.","enum":["audio/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"description":"What you wish the output audio to be. A strong, descriptive prompt that clearly defines\ninstruments, moods, styles, and genre will lead to better results.\n\nYou can make a prompt as simple or complex as you like. Simple prompts are good for clean\noutput audio. Complex prompts are good for adding texture and depth to the output audio."},"duration":{"type":"number","minimum":1,"maximum":190,"default":190,"description":"Controls the duration in seconds of the generated audio."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"steps":{"type":"integer","minimum":4,"maximum":8,"default":8,"description":"Controls the number of sampling steps."},"output_format":{"type":"string","enum":["mp3","wav"],"default":"mp3","description":"Dictates the `content-type` of the generated audio."},"audio":{"type":"string","description":"The audio to be use as the starting point for the generation.\n\nSupported Formats:\n- mp3\n- wav\n\nValidation Rule:\n- Audio must be between 6 and 190 seconds long","format":"binary","example":"./some/audio.mp3"},"mask_start":{"type":"number","minimum":0,"maximum":190,"default":30},"mask_end":{"type":"number","minimum":0,"maximum":190,"default":190}},"required":["prompt","audio"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated audio.\n\n To receive the bytes of the audio directly, specify `audio/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"mpeg":{"description":"raw bytes","value":"audio/mpeg"},"mpegJSON":{"description":"base64 encoded","value":"application/json; type=audio/mpeg"},"wav":{"description":"raw bytes","value":"audio/wav"},"wavJSON":{"description":"base64 encoded","value":"application/json; type=audio/wav"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS"]},"description":"Indicates the reason the generation finished. It is always `SUCCESS` for this endpoint.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"audio/mpeg":{"schema":{"type":"string","description":"The bytes of the generated audio.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated mpeg"},"application/json; type=audio/mpeg":{"schema":{"type":"object","properties":{"audio":{"type":"string","description":"The generated audio, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS"],"description":"The reason the generation finished. It is always `SUCCESS` for this endpoint.","example":"SUCCESS"}},"required":["audio","finish_reason"]}},"audio/wav":{"schema":{"type":"string","description":"The bytes of the generated audio.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated wav"},"application/json; type=audio/wav":{"schema":{"type":"object","properties":{"audio":{"type":"string","description":"The generated audio, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS"],"description":"The reason the generation finished. It is always `SUCCESS` for this endpoint.","example":"SUCCESS"}},"required":["audio","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Copyrighted Content Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"copyrighted_content","errors":["Our system has detected the presence of copyrighted content in your audio. To comply with our guidelines, we cannot process this request. Please upload a different audio file."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/audio/stable-audio/text-to-audio":{"post":{"tags":["Stable Audio"],"summary":"Text-to-Audio","description":"Stable Audio transforms existing audio samples into new high-quality compositions up to six minutes\nlong at 44.1kHz stereo using text instructions.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to\n[![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Audio_API.ipynb)\nor try Stable Audio for free at [stableaudio.com](https://stableaudio.com).\n\nThis endpoint is asynchronous — it returns a generation `id` immediately (HTTP 202).\nPoll `GET /v2beta/audio/results/{id}` to retrieve the result.\n\n### Credits\n\n**Stable Audio 3.0**\n\nFlat rate of 26 credits per successful generation.\n\nAs always, you will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests, time\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/audio/stable-audio/text-to-audio\",\n    headers={\"authorization\": f\"Bearer sk-MYAPIKEY\", \"accept\": \"audio/*\"},\n    files={\"none\": \"\"},\n    data={\n        \"prompt\": \"A cinematic orchestral piece with sweeping strings and dramatic brass.\",\n        \"output_format\": \"mp3\",\n        \"duration\": 30,\n    },\n)\n\nif response.status_code != 202:\n    raise Exception(str(response.json()))\n\ngeneration_id = response.json()[\"id\"]\n\nwhile True:\n    result = requests.get(\n        f\"https://api.stability.ai/v2beta/audio/results/{generation_id}\",\n        headers={\"authorization\": f\"Bearer sk-MYAPIKEY\", \"accept\": \"audio/*\"},\n    )\n    if result.status_code == 202:\n        print(\"Generation in-progress, retrying in 10 seconds...\")\n        time.sleep(10)\n    elif result.status_code == 200:\n        with open(\"./output.mp3\", \"wb\") as f:\n            f.write(result.content)\n        break\n    else:\n        raise Exception(str(result.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  prompt: \"A cinematic orchestral piece with sweeping strings and dramatic brass.\",\n  output_format: \"mp3\",\n  duration: 30,\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/audio/stable-audio/text-to-audio`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    headers: { Authorization: `Bearer sk-MYAPIKEY`, Accept: \"audio/*\" },\n  }\n);\n\nif (response.status !== 202) {\n  throw new Error(`${response.status}: ${JSON.stringify(response.data)}`);\n}\n\nconst { id: generationID } = response.data;\n\nwhile (true) {\n  const result = await axios.request({\n    url: `https://api.stability.ai/v2beta/audio/results/${generationID}`,\n    method: \"GET\",\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { Authorization: `Bearer sk-MYAPIKEY`, Accept: \"audio/*\" },\n  });\n\n  if (result.status === 202) {\n    console.log(\"Generation in-progress, retrying in 10 seconds...\");\n    await new Promise((resolve) => setTimeout(resolve, 10_000));\n  } else if (result.status === 200) {\n    fs.writeFileSync(\"./output.mp3\", Buffer.from(result.data));\n    break;\n  } else {\n    throw new Error(`${result.status}: ${result.data.toString()}`);\n  }\n}"},{"lang":"terminal","label":"cURL","source":"generation_id=$(curl -sS -f \"https://api.stability.ai/v2beta/audio/stable-audio/text-to-audio\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: audio/*\" \\\n  -F prompt=\"A cinematic orchestral piece with sweeping strings and dramatic brass.\" \\\n  -F output_format=\"mp3\" \\\n  -F duration=\"30\" \\\n  | jq -r '.id')\n\nwhile true; do\n  http_status=$(curl -sS -f \\\n    -o \"./output.mp3\" \\\n    -w '%{http_code}' \\\n    -H \"authorization: Bearer sk-MYAPIKEY\" \\\n    -H \"accept: audio/*\" \\\n    \"https://api.stability.ai/v2beta/audio/results/${generation_id}\")\n\n  case $http_status in\n    202) echo \"Still processing. Retrying in 10 seconds...\"; sleep 10 ;;\n    200) echo \"Download complete!\"; break ;;\n    *) echo \"Error: $http_status\"; exit 1 ;;\n  esac\ndone"}],"x-launchDarklyEnableFlag":"allow-access-stable-audio-3-api","parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"audio/*","description":"Specify `audio/*` to receive the bytes of the audio directly. Otherwise specify `application/json` to receive the audio as base64 encoded JSON.","enum":["audio/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"description":"What you wish the output audio to be. A strong, descriptive prompt that clearly defines\ninstruments, moods, styles, and genre will lead to better results.\n\nYou can make a prompt as simple or complex as you like. Simple prompts are good for clean\noutput audio. Complex prompts are good for adding texture and depth to the output audio."},"model":{"type":"string","enum":["stable-audio-3"],"default":"stable-audio-3","description":"The model to use for generation.\n\n- `stable-audio-3` requires 26 credits per generation"},"duration":{"type":"number","minimum":1,"maximum":380,"default":190,"description":"Controls the duration in seconds of the generated audio."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"steps":{"type":"integer","minimum":4,"maximum":8,"default":8,"description":"Controls the number of sampling steps."},"cfg_scale":{"type":"number","minimum":1,"maximum":25,"default":1,"description":"How strictly the diffusion process adheres to the prompt text (higher values make your audio closer to your prompt). Defaults to 1 if not specified."},"output_format":{"type":"string","enum":["mp3","wav"],"default":"mp3","description":"Dictates the `content-type` of the generated audio."}},"required":["prompt"]}}}},"responses":{"202":{"description":"Generation started. Use the returned id to poll for the result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/GenerationID"}},"required":["id"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Copyrighted Content Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"copyrighted_content","errors":["Our system has detected the presence of copyrighted content in your audio. To comply with our guidelines, we cannot process this request. Please upload a different audio file."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/audio/stable-audio/audio-to-audio":{"post":{"middleware":[null],"tags":["Stable Audio"],"summary":"Audio-to-Audio","description":"Stable Audio transforms existing audio samples into new high-quality compositions up to six minutes\nlong at 44.1kHz stereo using text instructions. Discover techniques for sample transformation in our\n[Audio to Audio Guide](https://www.stableaudio.com/user-guide/audio-to-audio) to maximize creative control.\nRead more about the model capabilities [here](https://stability.ai/news-updates).\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to\n[![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Audio_API.ipynb)\nor try Stable Audio for free at [stableaudio.com](https://stableaudio.com).\n\nThis endpoint is asynchronous — it returns a generation `id` immediately (HTTP 202).\nPoll `GET /v2beta/audio/results/{id}` to retrieve the result.\n\n> **Note:**\n> - We do not allow copyrighted content to be uploaded to our platform.\n> - Maximum request size is 100Mb.\n\n### Credits\n\n**Stable Audio 3.0**\n\nFlat rate of 26 credits per successful generation.\n\nAs always, you will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests, time\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/audio/stable-audio/audio-to-audio\",\n    headers={\"authorization\": f\"Bearer sk-MYAPIKEY\", \"accept\": \"audio/*\"},\n    files={\"audio\": open(\"./input.mp3\", \"rb\")},\n    data={\n        \"prompt\": \"Add a lush reverb and layer in warm ambient pads.\",\n        \"output_format\": \"mp3\",\n        \"duration\": 30,\n        \"strength\": 0.5,\n    },\n)\n\nif response.status_code != 202:\n    raise Exception(str(response.json()))\n\ngeneration_id = response.json()[\"id\"]\n\nwhile True:\n    result = requests.get(\n        f\"https://api.stability.ai/v2beta/audio/results/{generation_id}\",\n        headers={\"authorization\": f\"Bearer sk-MYAPIKEY\", \"accept\": \"audio/*\"},\n    )\n    if result.status_code == 202:\n        print(\"Generation in-progress, retrying in 10 seconds...\")\n        time.sleep(10)\n    elif result.status_code == 200:\n        with open(\"./output.mp3\", \"wb\") as f:\n            f.write(result.content)\n        break\n    else:\n        raise Exception(str(result.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  prompt: \"Add a lush reverb and layer in warm ambient pads.\",\n  output_format: \"mp3\",\n  duration: 30,\n  strength: 0.5,\n  audio: fs.createReadStream(\"./input.mp3\"),\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/audio/stable-audio/audio-to-audio`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    headers: { Authorization: `Bearer sk-MYAPIKEY`, Accept: \"audio/*\" },\n  }\n);\n\nif (response.status !== 202) {\n  throw new Error(`${response.status}: ${JSON.stringify(response.data)}`);\n}\n\nconst { id: generationID } = response.data;\n\nwhile (true) {\n  const result = await axios.request({\n    url: `https://api.stability.ai/v2beta/audio/results/${generationID}`,\n    method: \"GET\",\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { Authorization: `Bearer sk-MYAPIKEY`, Accept: \"audio/*\" },\n  });\n\n  if (result.status === 202) {\n    console.log(\"Generation in-progress, retrying in 10 seconds...\");\n    await new Promise((resolve) => setTimeout(resolve, 10_000));\n  } else if (result.status === 200) {\n    fs.writeFileSync(\"./output.mp3\", Buffer.from(result.data));\n    break;\n  } else {\n    throw new Error(`${result.status}: ${result.data.toString()}`);\n  }\n}"},{"lang":"terminal","label":"cURL","source":"generation_id=$(curl -sS -f \"https://api.stability.ai/v2beta/audio/stable-audio/audio-to-audio\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: audio/*\" \\\n  -F prompt=\"Add a lush reverb and layer in warm ambient pads.\" \\\n  -F output_format=\"mp3\" \\\n  -F duration=\"30\" \\\n  -F strength=\"0.5\" \\\n  -F audio=@\"./input.mp3\" \\\n  | jq -r '.id')\n\nwhile true; do\n  http_status=$(curl -sS -f \\\n    -o \"./output.mp3\" \\\n    -w '%{http_code}' \\\n    -H \"authorization: Bearer sk-MYAPIKEY\" \\\n    -H \"accept: audio/*\" \\\n    \"https://api.stability.ai/v2beta/audio/results/${generation_id}\")\n\n  case $http_status in\n    202) echo \"Still processing. Retrying in 10 seconds...\"; sleep 10 ;;\n    200) echo \"Download complete!\"; break ;;\n    *) echo \"Error: $http_status\"; exit 1 ;;\n  esac\ndone"}],"x-launchDarklyEnableFlag":"allow-access-stable-audio-3-api","parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"audio/*","description":"Specify `audio/*` to receive the bytes of the audio directly. Otherwise specify `application/json` to receive the audio as base64 encoded JSON.","enum":["audio/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"description":"What you wish the output audio to be. A strong, descriptive prompt that clearly defines\ninstruments, moods, styles, and genre will lead to better results.\n\nYou can make a prompt as simple or complex as you like. Simple prompts are good for clean\noutput audio. Complex prompts are good for adding texture and depth to the output audio."},"model":{"type":"string","enum":["stable-audio-3"],"default":"stable-audio-3","description":"The model to use for generation.\n\n- `stable-audio-3` requires 26 credits per generation"},"duration":{"type":"number","minimum":1,"maximum":380,"default":190,"description":"Controls the duration in seconds of the generated audio."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"steps":{"type":"integer","minimum":4,"maximum":8,"default":8,"description":"Controls the number of sampling steps."},"cfg_scale":{"type":"number","minimum":1,"maximum":25,"default":1,"description":"How strictly the diffusion process adheres to the prompt text (higher values make your audio closer to your prompt). Defaults to 1 if not specified."},"output_format":{"type":"string","enum":["mp3","wav"],"default":"mp3","description":"Dictates the `content-type` of the generated audio."},"strength":{"type":"number","minimum":0,"maximum":1,"default":1,"description":"Sometimes referred to as _denoising_, this parameter controls how much influence the\n`audio` parameter has on the generated audio.\nA value of 0 would yield audio that is identical to the input.\nA value of 1 would be as if you passed in no audio at all."},"audio":{"type":"string","description":"The audio to be used as the starting point for the generation.\n\nSupported Formats:\n- mp3\n- wav\n\nValidation Rule:\n- Audio must be between 6 and 380 seconds long","format":"binary","example":"./some/audio.mp3"}},"required":["prompt","audio"]}}}},"responses":{"202":{"description":"Generation started. Use the returned id to poll for the result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/GenerationID"}},"required":["id"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Copyrighted Content Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"copyrighted_content","errors":["Our system has detected the presence of copyrighted content in your audio. To comply with our guidelines, we cannot process this request. Please upload a different audio file."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/audio/stable-audio/inpaint":{"post":{"middleware":[null],"tags":["Stable Audio"],"summary":"Inpaint","description":"Stable Audio transforms existing audio samples into new high-quality compositions up to six minutes\nlong at 44.1kHz stereo using text instructions.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to\n[![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Audio_API.ipynb)\nor try Stable Audio for free at [stableaudio.com](https://stableaudio.com).\n\nThis endpoint is asynchronous — it returns a generation `id` immediately (HTTP 202).\nPoll `GET /v2beta/audio/results/{id}` to retrieve the result.\n\n> **Note:**\n> - We do not allow copyrighted content to be uploaded to our platform.\n> - Maximum request size is 100Mb.\n\n### Credits\n**Stable Audio 3.0**\n\nFlat rate of 26 credits per successful generation.\n\nAs always, you will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests, time\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/audio/stable-audio/inpaint\",\n    headers={\"authorization\": f\"Bearer sk-MYAPIKEY\", \"accept\": \"audio/*\"},\n    files={\"audio\": open(\"./input.mp3\", \"rb\")},\n    data={\n        \"prompt\": \"Replace the middle section with flowing piano and soft strings.\",\n        \"output_format\": \"mp3\",\n        \"duration\": 30,\n        \"mask_start\": 10,\n        \"mask_end\": 20,\n    },\n)\n\nif response.status_code != 202:\n    raise Exception(str(response.json()))\n\ngeneration_id = response.json()[\"id\"]\n\nwhile True:\n    result = requests.get(\n        f\"https://api.stability.ai/v2beta/audio/results/{generation_id}\",\n        headers={\"authorization\": f\"Bearer sk-MYAPIKEY\", \"accept\": \"audio/*\"},\n    )\n    if result.status_code == 202:\n        print(\"Generation in-progress, retrying in 10 seconds...\")\n        time.sleep(10)\n    elif result.status_code == 200:\n        with open(\"./output.mp3\", \"wb\") as f:\n            f.write(result.content)\n        break\n    else:\n        raise Exception(str(result.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  prompt: \"Replace the middle section with flowing piano and soft strings.\",\n  output_format: \"mp3\",\n  duration: 30,\n  mask_start: 10,\n  mask_end: 20,\n  audio: fs.createReadStream(\"./input.mp3\"),\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/audio/stable-audio/inpaint`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    headers: { Authorization: `Bearer sk-MYAPIKEY`, Accept: \"audio/*\" },\n  }\n);\n\nif (response.status !== 202) {\n  throw new Error(`${response.status}: ${JSON.stringify(response.data)}`);\n}\n\nconst { id: generationID } = response.data;\n\nwhile (true) {\n  const result = await axios.request({\n    url: `https://api.stability.ai/v2beta/audio/results/${generationID}`,\n    method: \"GET\",\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { Authorization: `Bearer sk-MYAPIKEY`, Accept: \"audio/*\" },\n  });\n\n  if (result.status === 202) {\n    console.log(\"Generation in-progress, retrying in 10 seconds...\");\n    await new Promise((resolve) => setTimeout(resolve, 10_000));\n  } else if (result.status === 200) {\n    fs.writeFileSync(\"./output.mp3\", Buffer.from(result.data));\n    break;\n  } else {\n    throw new Error(`${result.status}: ${result.data.toString()}`);\n  }\n}"},{"lang":"terminal","label":"cURL","source":"generation_id=$(curl -sS -f \"https://api.stability.ai/v2beta/audio/stable-audio/inpaint\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: audio/*\" \\\n  -F prompt=\"Replace the middle section with flowing piano and soft strings.\" \\\n  -F output_format=\"mp3\" \\\n  -F duration=\"30\" \\\n  -F mask_start=\"10\" \\\n  -F mask_end=\"20\" \\\n  -F audio=@\"./input.mp3\" \\\n  | jq -r '.id')\n\nwhile true; do\n  http_status=$(curl -sS -f \\\n    -o \"./output.mp3\" \\\n    -w '%{http_code}' \\\n    -H \"authorization: Bearer sk-MYAPIKEY\" \\\n    -H \"accept: audio/*\" \\\n    \"https://api.stability.ai/v2beta/audio/results/${generation_id}\")\n\n  case $http_status in\n    202) echo \"Still processing. Retrying in 10 seconds...\"; sleep 10 ;;\n    200) echo \"Download complete!\"; break ;;\n    *) echo \"Error: $http_status\"; exit 1 ;;\n  esac\ndone"}],"x-launchDarklyEnableFlag":"allow-access-stable-audio-3-api","parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"audio/*","description":"Specify `audio/*` to receive the bytes of the audio directly. Otherwise specify `application/json` to receive the audio as base64 encoded JSON.","enum":["audio/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"description":"What you wish the output audio to be. A strong, descriptive prompt that clearly defines\ninstruments, moods, styles, and genre will lead to better results.\n\nYou can make a prompt as simple or complex as you like. Simple prompts are good for clean\noutput audio. Complex prompts are good for adding texture and depth to the output audio."},"model":{"type":"string","enum":["stable-audio-3"],"default":"stable-audio-3","description":"The model to use for generation.\n\n- `stable-audio-3` requires 26 credits per generation"},"duration":{"type":"number","minimum":1,"maximum":380,"default":190,"description":"Controls the duration in seconds of the generated audio."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"steps":{"type":"integer","minimum":4,"maximum":8,"default":8,"description":"Controls the number of sampling steps."},"cfg_scale":{"type":"number","minimum":1,"maximum":25,"default":1,"description":"How strictly the diffusion process adheres to the prompt text (higher values make your audio closer to your prompt). Defaults to 1 if not specified."},"output_format":{"type":"string","enum":["mp3","wav"],"default":"mp3","description":"Dictates the `content-type` of the generated audio."},"mask_start":{"type":"number","minimum":0,"maximum":380,"default":30},"mask_end":{"type":"number","minimum":0,"maximum":380,"default":380},"audio":{"type":"string","description":"The audio to be used as the starting point for the generation.\n\nSupported Formats:\n- mp3\n- wav\n\nValidation Rule:\n- Audio must be between 6 and 380 seconds long","format":"binary","example":"./some/audio.mp3"}},"required":["prompt","audio"]}}}},"responses":{"202":{"description":"Generation started. Use the returned id to poll for the result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/GenerationID"}},"required":["id"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Copyrighted Content Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"copyrighted_content","errors":["Our system has detected the presence of copyrighted content in your audio. To comply with our guidelines, we cannot process this request. Please upload a different audio file."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/audio/results/{id}":{"get":{"tags":["Audio Results","Stable Audio"],"operationId":"fetchAudioResult","summary":"Fetch Audio Result","description":"Fetch the result of an audio generation by ID.\n\nPoll this endpoint after starting an async audio generation. Returns `202` while\nin-progress, `200` with the audio when complete.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\ngeneration_id = \"e52772ac75b...\"\nresult = requests.get(\n    f\"https://api.stability.ai/v2beta/audio/results/{generation_id}\",\n    headers={\"authorization\": f\"Bearer sk-MYAPIKEY\", \"accept\": \"audio/*\"},\n)\n\nif result.status_code == 202:\n    print(\"Generation is still in-progress.\")\nelif result.status_code == 200:\n    with open(\"./output.mp3\", \"wb\") as f:\n        f.write(result.content)\n    print(\"Download complete!\")\nelse:\n    raise Exception(str(result.json()))"},{"lang":"javascript","label":"JavaScript","source":"import axios from \"axios\";\nimport fs from \"node:fs\";\n\nconst generationID = \"e52772ac75b...\";\n\nconst response = await axios.request({\n  url: `https://api.stability.ai/v2beta/audio/results/${generationID}`,\n  method: \"GET\",\n  validateStatus: undefined,\n  responseType: \"arraybuffer\",\n  headers: {\n    Authorization: `Bearer sk-MYAPIKEY`,\n    Accept: \"audio/*\",\n  },\n});\n\nif (response.status === 202) {\n  console.log(\"Generation is still in-progress.\");\n} else if (response.status === 200) {\n  fs.writeFileSync(\"./output.mp3\", Buffer.from(response.data));\n  console.log(\"Download complete!\");\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"generation_id=\"e52772ac75b...\"\nhttp_status=$(curl -sS -f \\\n  -o \"./output.mp3\" \\\n  -w '%{http_code}' \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: audio/*\" \\\n  \"https://api.stability.ai/v2beta/audio/results/${generation_id}\")\n\ncase $http_status in\n  202) echo \"Still processing. Retrying in 10 seconds...\" ;;\n  200) echo \"Download complete!\" ;;\n  *) echo \"Error: $http_status\"; exit 1 ;;\nesac"}],"x-launchDarklyEnableFlag":"allow-access-stable-audio-3-api","parameters":[{"schema":{"$ref":"#/components/schemas/GenerationID"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","default":"audio/*","description":"Specify `audio/*` to receive the bytes of the audio directly. Otherwise specify `application/json` to receive the audio as base64 encoded JSON.","enum":["audio/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated audio.\n\n To receive the bytes of the audio directly, specify `audio/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"mpeg":{"description":"raw bytes","value":"audio/mpeg"},"mpegJSON":{"description":"base64 encoded","value":"application/json; type=audio/mpeg"},"wav":{"description":"raw bytes","value":"audio/wav"},"wavJSON":{"description":"base64 encoded","value":"application/json; type=audio/wav"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS"]},"description":"Indicates the reason the generation finished. It is always `SUCCESS` for this endpoint.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"audio/mpeg":{"schema":{"type":"string","description":"The bytes of the generated audio.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated mpeg"},"application/json; type=audio/mpeg":{"schema":{"type":"object","properties":{"audio":{"type":"string","description":"The generated audio, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS"],"description":"The reason the generation finished. It is always `SUCCESS` for this endpoint.","example":"SUCCESS"}},"required":["audio","finish_reason"]}},"audio/wav":{"schema":{"type":"string","description":"The bytes of the generated audio.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated wav"},"application/json; type=audio/wav":{"schema":{"type":"object","properties":{"audio":{"type":"string","description":"The generated audio, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS"],"description":"The reason the generation finished. It is always `SUCCESS` for this endpoint.","example":"SUCCESS"}},"required":["audio","finish_reason"]}}}},"202":{"description":"Your generation is still in-progress.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/GenerationID"},"status":{"type":"string","enum":["in-progress"],"description":"The status of your generation."}},"required":["id","status"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"404":{"description":"id: the generation either does not exist or has expired.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2bca35116bc5431d6dc4b4ea2ef3da2f","name":"generation_not_found","errors":["id: the generation either does not exist or has expired."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/upscale/conservative":{"post":{"tags":["Upscale"],"summary":"Conservative","description":"Takes images between 64x64 and 1 megapixel and upscales them all the way to 4K resolution. Put more generally, it can upscale images ~20-40x times while preserving all aspects. Conservative Upscale minimizes alterations to the image and should not be used to reimagine an image.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=t1Q4w2uvvza0)\n\n### How to use\n\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request must include:\n- `image`\n- `prompt`\n\nOptionally, the body of the request may also include:\n- `negative_prompt`\n- `seed`\n- `output_format`\n- `creativity`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will be 4 megapixels.\n\n### Credits\nFlat rate of 40 credits per successful generation.  You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/upscale/conservative\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./low-res-flower.jpg\", \"rb\"),\n    },\n    data={\n        \"prompt\": \"a flower\",\n        \"output_format\": \"webp\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./flower.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  image: fs.createReadStream(\"./low-res-flower.jpg\"),\n  prompt: \"a flower\",\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/upscale/conservative`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\" \n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./flower.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/upscale/conservative\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./low-res-flower.jpg\" \\\n  -F prompt=\"a flower\" \\\n  -F output_format=\"webp\" \\\n  -o \"./flower.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image you wish to upscale.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels\n- The aspect ratio must be between 1:2.5 and 2.5:1","format":"binary","example":"./some/image.png"},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"creativity":{"$ref":"#/components/schemas/Creativity"}},"required":["image","prompt"]}}}},"responses":{"200":{"description":"Upscale was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/upscale/creative":{"post":{"tags":["Upscale"],"summary":"Creative Upscale (async)","description":"Takes images between 64x64 and 1 megapixel and upscales them all the way to **4K** resolution.  Put more\ngenerally, it can upscale images ~20-40x times while preserving, and often enhancing, quality.\nCreative Upscale **works best on highly degraded images and is not for photos of 1mp or above** as it performs\nheavy reimagining (controlled by creativity scale).\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=QXxi9tfI425t)\n\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`.\n\nThe body of the request should include:\n- `image`\n- `prompt`\n\nThe body may optionally include:\n- `seed`\n- `negative_prompt`\n- `output_format`\n- `creativity`\n- `style_preset`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Results\nAfter invoking this endpoint with the required parameters, use the `id` in the response to poll for results at the\n[results/{id} endpoint](#tag/Results/paths/~1v2beta~1results~1%7Bid%7D/get).  Rate-limiting or other errors may occur if you poll more than once every 10 seconds.\n\n### Credits\nFlat rate of 60 credits per successful generation.  You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/upscale/creative\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./kitten-in-space.png\", \"rb\")\n    },\n    data={\n        \"prompt\": \"cute fluffy white kitten floating in space, pastel colors\",\n        \"output_format\": \"webp\",\n    },\n)\n\nprint(\"Generation ID:\", response.json().get('id'))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  image: fs.createReadStream(\"./kitten-in-space.png\"),\n  prompt: \"cute fluffy white kitten floating in space, pastel colors\",\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/upscale/creative`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`\n    },\n  },\n);\n\nconsole.log(\"Generation ID:\", response.data.id);"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/upscale/creative\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -F image=@\"./kitten-in-rainforest.png\" \\\n  -F prompt=\"cute fluffy white kitten sitting in a rainforest, pastel colors\" \\\n  -F output_format=webp \\\n  -o \"./output.json\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image you wish to upscale.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 1,048,576 pixels","format":"binary","example":"./some/image.png"},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"creativity":{"type":"number","minimum":0.1,"maximum":0.5,"default":0.3,"description":"Indicates how creative the model should be when upscaling an image.\nHigher values will result in more details being added to the image during upscaling."},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."}},"required":["image","prompt"]}}}},"responses":{"200":{"description":"Upscale was started.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/GenerationID"}},"required":["id"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/upscale/creative/result/{id}":{"get":{"tags":[],"summary":"Fetch Creative Upscale result","description":"Fetch the result of an upscale generation by ID. \n\nMake sure to use the same API key to fetch the generation result that you used to create the generation, \notherwise you will receive a `404` response.\n\n### How to use\nPlease invoke this endpoint with a `GET` request.\n\nThe headers of the request must include an API key in the `authorization` field and the ID\nof your generation must be in the path.\n\n### How is progress reported?\nYour generation is either `in-progress` (i.e. status code `202`) or it is complete (i.e. status code `200`). \nWe may add more fine-grained progress reporting in the future (e.g. a numerical progress).\n\n### How long are results stored?\nResults are stored for 24 hours after generation. After that, the results are deleted.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\ngeneration_id = \"e52772ac75b...\"\n\nresponse = requests.request(\n    \"GET\",\n    f\"https://api.stability.ai/v2beta/stable-image/upscale/creative/result/{generation_id}\",\n    headers={\n        'accept': \"image/*\",  # Use 'application/json' to receive base64 encoded JSON\n        'authorization': f\"Bearer sk-MYAPIKEY\"\n    },\n)\n\nif response.status_code == 202:\n    print(\"Generation in-progress, try again in 10 seconds.\")\nelif response.status_code == 200:\n    print(\"Generation complete!\")\n    with open(\"upscaled.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import axios from \"axios\";\nimport fs from \"node:fs\";\n\nconst generationID = \"e52772ac75b...\";\n\nconst response = await axios.request({\n  url: `https://api.stability.ai/v2beta/stable-image/upscale/creative/result/${generationID}`,\n  method: \"GET\",\n  validateStatus: undefined,\n  responseType: \"arraybuffer\",\n  headers: {\n    Authorization: `Bearer sk-MYAPIKEY`,\n    Accept: \"image/*\", // Use 'application/json' to receive base64 encoded JSON\n  },\n});\n\nif (response.status === 202) {\n  console.log(\"Generation is still running, try again in 10 seconds.\");\n} else if (response.status === 200) {\n  console.log(\"Generation is complete!\");\n  fs.writeFileSync(\"upscaled.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`Response ${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"generation_id=\"e52772ac75b...\"\nurl=\"https://api.stability.ai/v2beta/stable-image/upscale/creative/result/$generation_id\"\nhttp_status=$(curl -sS -f -o \"./upscaled.webp\" -w '%{http_code}' -H \"authorization: sk-MYAPIKEY\" -H 'accept: image/*' \"$url\")\n\ncase $http_status in\n    202)\n        echo \"Still processing. Retrying in 10 seconds...\"\n        ;;\n    200)\n        echo \"Download complete!\"\n        ;;\n    4*|5*)\n        mv \"./upscaled.webp\" \"./error.json\"\n        echo \"Error: Check ./error.json for details.\"\n        exit 1\n        ;;\nesac"}],"parameters":[{"schema":{"$ref":"#/components/schemas/GenerationID"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"responses":{"200":{"description":"Upscale finished.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"202":{"description":"Your upscale generation is still in-progress.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/GenerationID"},"status":{"type":"string","enum":["in-progress"],"description":"The status of your generation."}},"required":["id","status"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"404":{"description":"id: the generation either does not exist or has expired.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2bca35116bc5431d6dc4b4ea2ef3da2f","name":"generation_not_found","errors":["id: the generation either does not exist or has expired."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/upscale/fast":{"post":{"tags":["Upscale"],"summary":"Fast","description":"Our Fast Upscaler service enhances image resolution by 4x using predictive and generative AI. This lightweight and fast service (processing in ~1 second) is ideal for enhancing the quality of compressed images, making it suitable for social media posts and other applications.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=t1Q4w2uvvza0)\n\n### How to use\n\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request must include:\n- `image`\n\nOptionally, the body of the request may also include:\n- `output_format`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image is 4 times that of the input image with a maximum size of 16 megapixels.\n\n### Credits\nFlat rate of 2 credit per successful generation. You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/upscale/fast\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./low-res-flower.jpg\", \"rb\"),\n    },\n    data={\n        \"output_format\": \"webp\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./flower.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  image: fs.createReadStream(\"./low-res-flower.jpg\"),\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/upscale/fast`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\" \n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./flower.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/upscale/fast\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./low-res-flower.jpg\" \\\n  -F output_format=\"webp\" \\\n  -o \"./flower.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image you wish to upscale.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Width must be between 32 and 1,536 pixels\n- Height must be between 32 and 1,536 pixels\n- Total pixel count must be between 1,024 and 1,048,576 pixels","format":"binary","example":"./some/image.png"},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."}},"required":["image"]}}}},"responses":{"200":{"description":"Upscale was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/edit/erase":{"post":{"tags":["Edit"],"summary":"Erase","description":"The Erase service removes unwanted objects, such as blemishes on portraits or items on desks, using image masks.\n\nThe mask is provided in one of two ways:\n  1. Explicitly passing in a separate image via the `mask` parameter\n  2. Derived from the alpha channel of the `image` parameter.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=t1Q4w2uvvza0)\n\n### How to use\n\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request must include:\n- `image`\n\nOptionally, the body of the request may also include:\n- `mask`\n- `seed`\n- `output_format`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will be 4 megapixels.\n\n### Credits\nFlat rate of 5 credits per successful generation.  You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/edit/erase\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./kangaroo-on-the-beach.png\", \"rb\"),\n        \"mask\": open(\"./mask-of-kangaroo.png\", \"rb\"),\n    },\n    data={\n        \"output_format\": \"webp\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./just-the-beach.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  image: fs.createReadStream(\"./kangaroo-on-the-beach.png\"),\n  mask: fs.createReadStream(\"./mask-of-kangaroo.png\"),\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/edit/erase`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\" \n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./just-the-beach.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/edit/erase\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./kangaroo-on-the-beach.png\" \\\n  -F mask=@\"./mask-of-kangaroo.png\" \\\n  -F output_format=\"webp\" \\\n  -o \"./just-the-beach.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image you wish to erase from.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels","format":"binary","example":"./some/image.png"},"mask":{"type":"string","description":"Controls the strength of the inpainting process on a per-pixel basis, either via a\nsecond image (passed into this parameter) or via the alpha channel of the `image` parameter.\n\n**Passing in a Mask**\n\nThe image passed to this parameter should be a black and white image that represents,\nat any pixel, the strength of inpainting based on how dark or light the given pixel is.\nCompletely black pixels represent no inpainting strength while completely white pixels\nrepresent maximum strength.\n\nIn the event the mask is a different size than the `image` parameter, it will be automatically resized.\n\n**Alpha Channel Support**\n\nIf you don't provide an explicit mask, one will be derived from the alpha channel of the `image` parameter.\nTransparent pixels will be inpainted while opaque pixels will be preserved.\n\nIn the event an `image` with an alpha channel is provided along with a `mask`, the `mask` will take precedence.","format":"binary","example":"./some/image.png"},"grow_mask":{"type":"number","minimum":0,"maximum":20,"default":5,"description":"Grows the edges of the mask outward in all directions by the specified number of pixels. The expanded area around the mask will be blurred, which can help smooth the transition between inpainted content and the original image.\n\nTry this parameter if you notice seams or rough edges around the inpainted content.\n\n> Note: Excessive growth may obscure fine details in the mask and/or merge nearby masked regions."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."}},"required":["image","prompt"]}}}},"responses":{"200":{"description":"Erase was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/edit/inpaint":{"post":{"tags":["Edit"],"summary":"Inpaint","description":"Intelligently modify images by filling in or replacing specified areas with new content based\non the content of a \"mask\" image.\n\nThe \"mask\" is provided in one of two ways:\n  1. Explicitly passing in a separate image via the `mask` parameter\n  2. Derived from the alpha channel of the `image` parameter.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=t1Q4w2uvvza0)\n\n### How to use\n\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request must include:\n- `image`\n- `prompt`\n\nOptionally, the body of the request may also include:\n- `mask`\n- `negative_prompt`\n- `seed`\n- `output_format`\n- `style_preset`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will be 4 megapixels.\n\n### Credits\nFlat rate of 5 credits per successful generation.  You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/edit/inpaint\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./dog-wearing-vr-goggles.png\", \"rb\"),\n        \"mask\": open(\"./mask.png\", \"rb\"),\n    },\n    data={\n        \"prompt\": \"dog wearing black glasses\",\n        \"output_format\": \"webp\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./dog-wearing-black-glasses.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  image: fs.createReadStream(\"./dog-wearing-vr-goggles.png\"),\n  mask: fs.createReadStream(\"./mask.png\"),\n  prompt: \"dog wearing black glasses\",\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/edit/inpaint`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\" \n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./dog-wearing-black-glasses.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/edit/inpaint\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./dog-wearing-vr-goggles.png\" \\\n  -F mask=@\"./mask.png\" \\\n  -F prompt=\"golden retriever in a field\" \\\n  -F output_format=\"webp\" \\\n  -o \"./dog-wearing-black-glasses.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image you wish to inpaint.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels","format":"binary","example":"./some/image.png"},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"mask":{"type":"string","description":"Controls the strength of the inpainting process on a per-pixel basis, either via a\nsecond image (passed into this parameter) or via the alpha channel of the `image` parameter.\n\n**Passing in a Mask**\n\nThe image passed to this parameter should be a black and white image that represents,\nat any pixel, the strength of inpainting based on how dark or light the given pixel is.\nCompletely black pixels represent no inpainting strength while completely white pixels\nrepresent maximum strength.\n\nIn the event the mask is a different size than the `image` parameter, it will be automatically resized.\n\n**Alpha Channel Support**\n\nIf you don't provide an explicit mask, one will be derived from the alpha channel of the `image` parameter.\nTransparent pixels will be inpainted while opaque pixels will be preserved.\n\nIn the event an `image` with an alpha channel is provided along with a `mask`, the `mask` will take precedence.","format":"binary","example":"./some/image.png"},"grow_mask":{"type":"number","minimum":0,"maximum":100,"default":5,"description":"Grows the edges of the mask outward in all directions by the specified number of pixels. The expanded area around the mask will be blurred, which can help smooth the transition between inpainted content and the original image.\n\nTry this parameter if you notice seams or rough edges around the inpainted content.\n\n> Note: Excessive growth may obscure fine details in the mask and/or merge nearby masked regions."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."}},"required":["image","prompt"]}}}},"responses":{"200":{"description":"Inpainting was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/edit/outpaint":{"post":{"tags":["Edit"],"summary":"Outpaint","description":"The Outpaint service inserts additional content in an image to fill in the space in any direction.\nCompared to other automated or manual attempts to expand the content in an image, the Outpaint service\nshould minimize artifacts and signs that the original image has been edited.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=bZ2yK7VQSgLw)\n\n### How to use\n\nPlease invoke this endpoint with a POST request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request must include:\n- `image`\n\nAlong with _at least one_ outpaint direction:\n- `left`\n- `right`\n- `up`\n- `down`\n\n> **Note:** for best quality use outpaint direction values smaller or equal to your source image dimensions.\n\nEach of these parameters should be set to a number between 0 and 2000, representing the number of pixels to outpaint in that direction.\n\nOptionally, the body of the request may also include:\n- `prompt`\n- `seed`\n- `output_format`\n- `creativity`\n- `style_preset`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Credits\nFlat rate of 4 credits per successful generation.  You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/edit/outpaint\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./husky-in-a-field.png\", \"rb\")\n    },\n    data={\n        \"left\": 200,\n        \"down\": 200,\n        \"output_format\": \"webp\"\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./husky-in-a-huge-field.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  image: fs.createReadStream(\"./husky-in-a-field.png\"),\n  left: 200,\n  down: 200,\n  output_format: \"webp\",\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/edit/outpaint`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\" \n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./husky-in-a-huge-field.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/edit/outpaint\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./husky-in-a-field.png\" \\\n  -F left=200 \\\n  -F bottom=200 \\\n  -F output_format=\"webp\" \\\n  -o \"./husky-in-a-huge-field.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image you wish to outpaint.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels\n- The aspect ratio must be between 1:2.5 and 2.5:1","format":"binary","example":"./some/image.png"},"left":{"type":"integer","minimum":0,"maximum":2000,"default":0,"description":"The number of pixels to outpaint on the left side of the image. At least one outpainting direction must be supplied with a non-zero value."},"right":{"type":"integer","minimum":0,"maximum":2000,"default":0,"description":"The number of pixels to outpaint on the right side of the image. At least one outpainting direction must be supplied with a non-zero value."},"up":{"type":"integer","minimum":0,"maximum":2000,"default":0,"description":"The number of pixels to outpaint on the top of the image. At least one outpainting direction must be supplied with a non-zero value."},"down":{"type":"integer","minimum":0,"maximum":2000,"default":0,"description":"The number of pixels to outpaint on the bottom of the image. At least one outpainting direction must be supplied with a non-zero value."},"creativity":{"allOf":[{"$ref":"#/components/schemas/Creativity"},{"minimum":0,"maximum":1,"default":0.5}]},"prompt":{"type":"string","minLength":0,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["png","jpeg","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."}},"required":["image"]}}}},"responses":{"200":{"description":"Outpainting was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/edit/search-and-replace":{"post":{"tags":["Edit"],"summary":"Search and Replace","description":"The Search and Replace service is a specific version of inpainting that does not require a mask.\nInstead, users can leverage a `search_prompt` to identify an object in simple language to be replaced.\nThe service will automatically segment the object and replace it with the object requested in the prompt.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=0lDpGa2jAmAs)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request should include:\n- `image`\n- `prompt`\n- `search_prompt`\n\nThe body may optionally include:\n- `seed`\n- `negative_prompt`\n- `output_format`\n- `style_preset`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will be 4 megapixels.\n\n### Credits\nFlat rate of 5 credits per successful generation.  You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/edit/search-and-replace\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./husky-in-a-field.png\", \"rb\")\n    },\n    data={\n        \"prompt\": \"golden retriever in a field\",\n        \"search_prompt\": \"dog\",\n        \"output_format\": \"webp\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./golden-retriever-in-a-field.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  image: fs.createReadStream(\"./husky-in-a-field.png\"),\n  prompt: \"golden retriever standing in a field\",\n  search_prompt: \"dog\",\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/edit/search-and-replace`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\"\n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./golden-retriever-in-a-field.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/edit/search-and-replace\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./husky-in-a-field.png\" \\\n  -F prompt=\"golden retriever in a field\" \\\n  -F search_prompt=\"dog\" \\\n  -F output_format=\"webp\" \\\n  -o \"./golden-retriever-in-a-field.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"An image containing content you wish to replace.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels\n- The aspect ratio must be between 1:2.5 and 2.5:1","format":"binary","example":"./some/image.png"},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"search_prompt":{"type":"string","maxLength":10000,"description":"Short description of what to inpaint in the `image`.","example":"glasses"},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"grow_mask":{"type":"number","minimum":0,"maximum":20,"default":3,"description":"Grows the edges of the mask outward in all directions by the specified number of pixels. The expanded area around the mask will be blurred, which can help smooth the transition between inpainted content and the original image.\n\nTry this parameter if you notice seams or rough edges around the inpainted content.\n\n> Note: Excessive growth may obscure fine details in the mask and/or merge nearby masked regions."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."}},"required":["image","prompt","search_prompt"]}}}},"responses":{"200":{"description":"Search-and-Replace was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/edit/search-and-recolor":{"post":{"tags":["Edit"],"summary":"Search and Recolor","description":"The Search and Recolor service provides the ability to change the color of a specific object in an image using a prompt.\nThis service is a specific version of inpainting that does not require a mask. The Search and Recolor\nservice will automatically segment the object and recolor it using the colors requested in the prompt.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=mtgSh4Stj3l)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request should include:\n- `image`\n- `prompt`\n- `select_prompt`\n\nThe body may optionally include:\n- `grow_mask`\n- `seed`\n- `negative_prompt`\n- `output_format`\n- `style_preset`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will match the resolution of the input image.\n\n### Credits\nFlat rate of 5 credits per successful generation.  You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/edit/search-and-recolor\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./red-car.png\", \"rb\")\n    },\n    data={\n        \"prompt\": \"a yellow car\",\n        \"select_prompt\": \"car\",\n        \"output_format\": \"webp\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./yellow-car.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  image: fs.createReadStream(\"./red-car.png\"),\n  prompt: \"a yellow car\",\n  select_prompt: \"car\",\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/edit/search-and-recolor`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\"\n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./yellow-car.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/edit/search-and-recolor\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./red-car.png\" \\\n  -F prompt=\"a yellow car\" \\\n  -F select_prompt=\"car\" \\\n  -F output_format=\"webp\" \\\n  -o \"./yellow-car.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"An image containing content you wish to recolor.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels\n- The aspect ratio must be between 1:2.5 and 2.5:1","format":"binary","example":"./some/image.png"},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"select_prompt":{"type":"string","maxLength":10000,"description":"Short description of what to search for in the `image`.","example":"glasses"},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"grow_mask":{"type":"number","minimum":0,"maximum":20,"default":3,"description":"Grows the edges of the mask outward in all directions by the specified number of pixels. The expanded area around the mask will be blurred, which can help smooth the transition between inpainted content and the original image.\n\nTry this parameter if you notice seams or rough edges around the inpainted content.\n\n> Note: Excessive growth may obscure fine details in the mask and/or merge nearby masked regions."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."}},"required":["image","prompt","select_prompt"]}}}},"responses":{"200":{"description":"Search-and-Recolor was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/edit/remove-background":{"post":{"tags":["Edit"],"summary":"Remove Background","description":"The Remove Background service accurately segments the foreground from an image and implements \nand removes the background.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=VHofb3LAVmqi)\n\n\n### How to use\n\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n  \nThe body of the request must include:\n- `image`\n\nOptionally, the body of the request may also include:\n- `output_format`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Credits\nFlat rate of 5 credits per successful generation.  You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/edit/remove-background\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./husky-in-a-field.png\", \"rb\")\n    },\n    data={\n        \"output_format\": \"webp\"\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./husky.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  image: fs.createReadStream(\"./husky-in-a-field.png\"),\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/edit/remove-background`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\" \n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./husky.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/edit/remove-background\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./husky-in-a-field.png\" \\\n  -F output_format=\"webp\" \\\n  -o \"./husky.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image whose background you wish to remove.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 4,194,304 pixels","format":"binary","example":"./some/image.png"},"output_format":{"type":"string","enum":["png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."}},"required":["image"]}}}},"responses":{"200":{"description":"Background successfully removed.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/edit/replace-background-and-relight":{"post":{"tags":["Edit"],"summary":"Replace Background and Relight (async)","description":"The Replace Background and Relight edit service lets users swap backgrounds with\nAI-generated or uploaded images while adjusting lighting to match the subject. This\nnew API provides a streamlined image editing solution and can serve e-commerce, real\nestate, photography, and creative projects.\n\nSome of the things you can do include:\n  - Background Replacement: Remove existing background and add new ones.\n  - AI Background Generation: Create new backgrounds using AI generated images based on prompts.\n  - Relighting: Adjust lighting in images that are under or overexposed.\n  - Flexible Inputs: Use your own background image or generate one.\n  - Lighting Adjustments: Modify light reference, direction, and strength.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=mtgSh4Stj3l)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`.\n\nThe body of the request should include:\n- `subject_image`\n- `background_prompt` and/or `background_reference`\n\nThe body may optionally include:\n- `light_reference` or `light_source_direction`\n- `light_source_strength` (requires `light_reference` or `light_source_direction`)\n- `foreground_prompt`\n- `negative_prompt`\n- `preserve_original_subject`\n- `original_background_depth`\n- `keep_original_background`\n- `light_source_strength`\n- `seed`\n- `output_format`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Results\nAfter invoking this endpoint with the required parameters, use the `id` in the response to poll for results at the\n[results/{id} endpoint](#tag/Results/paths/~1v2beta~1results~1%7Bid%7D/get).  Rate-limiting or other errors may occur if you poll more than once every 10 seconds.\n\n### Credits\nFlat rate of 8 credits per successful generation. You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/edit/replace-background-and-relight\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"subject_image\": open(\"./husky-in-a-field.png\", \"rb\")\n    },\n    data={\n        \"background_prompt\": \"cinematic lighting\",\n        \"output_format\": \"webp\",\n    },\n)\n\nprint(\"Generation ID:\", response.json().get('id'))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  subject_image: fs.createReadStream(\"./husky-in-a-field.png\"),\n  background_prompt: \"cinematic lighting\",\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/edit/replace-background-and-relight`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n    },\n  },\n);\n\nconsole.log(\"Generation ID:\", response.data.id);"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/edit/replace-background-and-relight\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F subject_image=@\"./husky-in-a-field.png\" \\\n  -F background_prompt=\"cinematic lighting\" \\\n  -F output_format=\"webp\" \\\n  -o \"./output.json\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"subject_image":{"type":"string","description":"An image containing the subject that you wish to change background and relight.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels\n- The aspect ratio must be between 1:2.5 and 2.5:1","format":"binary","example":"./some/image.png"},"background_reference":{"type":"string","description":"An image whose style you wish to use in the background. Similar to the Control: Style API,\nstylistic elements from this image are added to the background.\n\n> **Important:** either `background_reference` or `background_prompt` must be provided.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels","format":"binary","example":"./some/image.png"},"background_prompt":{"type":"string","maxLength":10000,"description":"What you wish to see in the background of the output image. This could be a description\nof the desired background scene, or just a description of the lighting if modifying the\nlight source through `light_source_direction` or `light_reference`.\n\n> **Important:** either `background_reference` or `background_prompt` must be provided."},"foreground_prompt":{"type":"string","maxLength":10000,"description":"Description of the subject. Use this to prevent elements of the background from\nbleeding into the subject. For example, if you find your subject is turning\ngreen with a forest in the background, try putting a short description of the\nsubject in this field."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"preserve_original_subject":{"type":"number","minimum":0,"maximum":1,"default":0.6,"description":"How much to overlay the original subject to exactly match the original image. A\n1.0 is an exact pixel match for the subject, and 0.0 is a close match but will\nhave new lighting qualities. This is an advanced feature."},"original_background_depth":{"type":"number","minimum":0,"maximum":1,"default":0.5,"description":"Controls the generated background to have the same depth as the original subject image. This is an advanced feature."},"keep_original_background":{"type":"string","enum":["true","false"],"default":"false","description":"Whether to keep the background of the original image. When this is on, the background\nwill have different lighting than the original image that changes based on the other\nparameters in this API."},"light_source_direction":{"type":"string","enum":["left","right","above","below"],"description":"Direction of the light source."},"light_reference":{"type":"string","description":"An image with the desired lighting. Lighter sections of the light_reference image will correspond to sections with brighter lighting in the output image.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels","format":"binary","example":"./some/image.png"},"light_source_strength":{"type":"number","minimum":0,"maximum":1,"default":0.3,"description":"If using `light_reference_image` or `light_source_direction`, controls the strength\nof the light source. 1.0 is brighter and 0.0 is dimmer. This is an advanced feature.\n\n> **Important:** Use of this parameter requires `light_reference` or `light_source_direction` to be provided."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."}},"required":["subject_image"]}}}},"responses":{"200":{"description":"Replace Background and Relight was started.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/GenerationID"}},"required":["id"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/generate/ultra":{"post":{"tags":["Generate"],"summary":"Stable Image Ultra","description":"Our most advanced text to image generation service, Stable Image Ultra creates the highest quality images\nwith unprecedented prompt understanding. Ultra excels in typography, complex compositions, dynamic lighting,\nvibrant hues, and overall cohesion and structure of an art piece. Made from the most advanced models,\nincluding Stable Diffusion 3.5, Ultra offers the best of the Stable Diffusion ecosystem.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=yXhs626oZdr1)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`.  The accept header should be set to one of the following:\n- `image/*` to receive the image in the format specified by the `output_format` parameter.\n- `application/json` to receive the image in the format specified by the `output_format` parameter, but encoded to base64 in a JSON response.\n\nThe only required parameter is the `prompt` field, which should contain the text prompt for the image generation.\n\nThe body of the request should include:\n- `prompt` - text to generate the image from\n\nThe body may optionally include:\n- `image` - the image to use as the starting point for the generation\n- `strength` - controls how much influence the `image` parameter has on the output image\n- `aspect_ratio` - the aspect ratio of the output image\n- `negative_prompt` - keywords of what you **do not** wish to see in the output image\n- `seed` - the randomness seed to use for the generation\n- `output_format` - the format of the output image\n\n> **Note:** for the full list of optional parameters, please see the request schema below.\n\n### Output\nThe resolution of the generated image will be 1 megapixel. The default resolution is 1024x1024.\n\n### Credits\nThe Ultra service uses 8 credits per successful result. You will not be charged for failed results.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/generate/ultra\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\"none\": ''},\n    data={\n        \"prompt\": \"Lighthouse on a cliff overlooking the ocean\",\n        \"output_format\": \"webp\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./lighthouse.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  prompt: \"Lighthouse on a cliff overlooking the ocean\",\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/generate/ultra`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\" \n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./lighthouse.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/generate/ultra\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F prompt=\"Lighthouse on a cliff overlooking the ocean\" \\\n  -F output_format=\"webp\" \\\n  -o \"./lighthouse.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"aspect_ratio":{"type":"string","enum":["21:9","16:9","3:2","5:4","1:1","4:5","2:3","9:16","9:21"],"default":"1:1","description":"Controls the aspect ratio of the generated image."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["jpeg","png","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"image":{"type":"string","description":"The image to use as the starting point for the generation.\n\n> **Important:** The `strength` parameter is required when `image` is provided.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Width must be between 64 and 16,384 pixels\n- Height must be between 64 and 16,384 pixels\n- Total pixel count must be at least 4,096 pixels","format":"binary","example":"./some/image.png"},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."},"strength":{"type":"number","minimum":0,"maximum":1,"description":"Sometimes referred to as _denoising_, this parameter controls how much influence the \n`image` parameter has on the generated image.  A value of 0 would yield an image that \nis identical to the input.  A value of 1 would be as if you passed in no image at all.\n\n> **Important:** This parameter is required when `image` is provided."}},"required":["prompt"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/generate/core":{"post":{"tags":["Generate"],"summary":"Stable Image Core","description":"Our primary service for text-to-image generation, Stable Image Core represents the best quality achievable at high\nspeed. No prompt engineering is required! Try asking for a style, a scene, or a character, and see what you get.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=yXhs626oZdr1)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request should include:\n- `prompt`\n\nThe body may optionally include:\n- `aspect_ratio`\n- `negative_prompt`\n- `seed`\n- `style_preset`\n- `output_format`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will be 1.5 megapixels.\n\n### Credits\nFlat rate of 3 credits per successful generation.  You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/generate/core\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\"none\": ''},\n    data={\n        \"prompt\": \"Lighthouse on a cliff overlooking the ocean\",\n        \"output_format\": \"webp\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./lighthouse.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  prompt: \"Lighthouse on a cliff overlooking the ocean\",\n  output_format: \"webp\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/generate/core`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\" \n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./lighthouse.webp\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/generate/core\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F prompt=\"Lighthouse on a cliff overlooking the ocean\" \\\n  -F output_format=\"webp\" \\\n  -o \"./lighthouse.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"aspect_ratio":{"type":"string","enum":["21:9","16:9","3:2","5:4","1:1","4:5","2:3","9:16","9:21"],"default":"1:1","description":"Controls the aspect ratio of the generated image."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."},"output_format":{"type":"string","enum":["png","jpeg","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."}},"required":["prompt"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/generate/sd3":{"post":{"tags":["Generate"],"summary":"Stable Diffusion 3.5","description":"Generate using Stable Diffusion 3.5 models, Stability AI latest base model:\n\n- **Stable Diffusion 3.5 Large**: At 8 billion parameters, with superior quality and\n  prompt adherence, this base model is the most powerful in the Stable Diffusion\n  family. This model is ideal for professional use cases at 1 megapixel resolution.\n\n- **Stable Diffusion 3.5 Large Turbo**: A distilled version of Stable Diffusion 3.5 Large.\n  SD3.5 Large Turbo generates high-quality images with exceptional prompt adherence\n  in just 4 steps, making it considerably faster than Stable Diffusion 3.5 Large.\n\n- **Stable Diffusion 3.5 Medium**: With 2.5 billion parameters, the model delivers an\n  optimal balance between prompt accuracy and image quality, making it an efficient\n  choice for fast high-performance image generation.\n\n- **Stable Diffusion 3.5 Flash**: A distilled version of Stable Diffusion 3.5 Medium. \n  SD3.5 Flash generates high-quality images with a 4 step process instead of 40, making \n  it faster than Stable Diffusion 3.5 Medium.\n\nRead more about the model capabilities [here](https://stability.ai/news/introducing-stable-diffusion-3-5).\n\nAs of April 17, 2025, we have deprecated the Stable Diffusion 3.0 APIs and will be automatically\nre-routing calls to Stable Diffusion 3.0 models to Stable Diffusion 3.5 APIs at no extra cost.\nYou can read more in the [release notes](/docs/release-notes#api-deprecation-notice).\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/SD3_API.ipynb)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`.  The accept header should be set to one of the following:\n- `image/*` to receive the image in the format specified by the `output_format` parameter.\n- `application/json` to receive the image encoded as base64 in a JSON response.\n\n#### **Generating with a prompt**\nCommonly referred to as **text-to-image**, this mode generates an image from text alone. While the only required\nparameter is the `prompt`, it also supports an `aspect_ratio` parameter which can be used to control the\naspect ratio of the generated image.\n\n#### **Generating with a prompt *and* an image**\nCommonly referred to as **image-to-image**, this mode also generates an image from text but uses an existing image as the\nstarting point. The required parameters are:\n- `prompt` - text to generate the image from\n- `image` - the image to use as the starting point for the generation\n- `strength` - controls how much influence the `image` parameter has on the output image\n- `mode` - must be set to `image-to-image`\n\n> **Note:** maximum request size is 10MiB.\n\n#### **Optional Parameters:**\nBoth modes support the following optional parameters:\n- `model` - the model to use (SD 3.5 Large, SD 3.5 Large Turbo, SD 3.5 Medium, SD 3.5 Flash)\n- `output_format` - the format of the output image\n- `seed` - the randomness seed to use for the generation\n- `negative_prompt` - keywords of what you **do not** wish to see in the output image\n- `cfg_scale` - controls how strictly the diffusion process adheres to the prompt text\n- `style_preset` - guides the image model towards a particular style\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will be 1MP. The default resolution is 1024x1024.\n\n### Credits\n- **SD 3.5 Large**: Flat rate of 6.5 credits per successful generation.\n- **SD 3.5 Large Turbo**: Flat rate of 4 credits per successful generation.\n- **SD 3.5 Medium**: Flat rate of 3.5 credits per successful generation.\n- **SD 3.5 Flash**: Flat rate of 2.5 credits per successful generation.\n\nAs always, you will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/generate/sd3\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\"none\": ''},\n    data={\n        \"prompt\": \"Lighthouse on a cliff overlooking the ocean\",\n        \"output_format\": \"jpeg\",\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./lighthouse.jpeg\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import fs from \"node:fs\";\nimport axios from \"axios\";\nimport FormData from \"form-data\";\n\nconst payload = {\n  prompt: \"Lighthouse on a cliff overlooking the ocean\",\n  output_format: \"jpeg\"\n};\n\nconst response = await axios.postForm(\n  `https://api.stability.ai/v2beta/stable-image/generate/sd3`,\n  axios.toFormData(payload, new FormData()),\n  {\n    validateStatus: undefined,\n    responseType: \"arraybuffer\",\n    headers: { \n      Authorization: `Bearer sk-MYAPIKEY`, \n      Accept: \"image/*\" \n    },\n  },\n);\n\nif(response.status === 200) {\n  fs.writeFileSync(\"./lighthouse.jpeg\", Buffer.from(response.data));\n} else {\n  throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/generate/sd3\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F prompt=\"Lighthouse on a cliff overlooking the ocean\" \\\n  -F output_format=\"jpeg\" \\\n  -o \"./lighthouse.jpeg\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results."},"mode":{"type":"string","enum":["text-to-image","image-to-image"],"default":"text-to-image","description":"Controls whether this is a text-to-image or image-to-image generation, which affects which parameters are required:\n- **text-to-image** requires only the `prompt` parameter\n- **image-to-image** requires the `prompt`, `image`, and `strength` parameters","title":"GenerationMode"},"image":{"type":"string","description":"The image to use as the starting point for the generation.\n\nSupported formats:\n  - jpeg\n  - png\n  - webp\n\nSupported dimensions:\n  - Every side must be at least 64 pixels\n\n> **Important:** This parameter is only valid for **image-to-image** requests.","format":"binary"},"strength":{"type":"number","minimum":0,"maximum":1,"description":"Sometimes referred to as _denoising_, this parameter controls how much influence the\n`image` parameter has on the generated image.  A value of 0 would yield an image that\nis identical to the input.  A value of 1 would be as if you passed in no image at all.\n\n> **Important:** This parameter is only valid for **image-to-image** requests. For SD 3.5 Flash, the\n best results for image-to-image generation are achieved with a `strength` between .94 - .97."},"aspect_ratio":{"type":"string","enum":["21:9","16:9","3:2","5:4","1:1","4:5","2:3","9:16","9:21"],"default":"1:1","description":"Controls the aspect ratio of the generated image. Defaults to 1:1.\n\n> **Important:** This parameter is only valid for **text-to-image** requests."},"model":{"type":"string","enum":["sd3.5-large","sd3.5-large-turbo","sd3.5-medium"],"default":"sd3.5-large","description":"The model to use for generation.\n\n- `sd3.5-large` requires 6.5 credits per generation\n- `sd3.5-large-turbo` requires 4 credits per generation\n- `sd3.5-medium` requires 3.5 credits per generation\n- `sd3.5-flash` requires 2.5 credits per generation\n- As of the April 17, 2025, `sd3-large`, `sd3-large-turbo` and `sd3-medium`\n  are re-routed to their `sd3.5-[model version]` equivalent, at the same price."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["png","jpeg","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."},"negative_prompt":{"type":"string","maxLength":10000,"description":"Keywords of what you **do not** wish to see in the output image.\nThis is an advanced feature."},"cfg_scale":{"type":"number","minimum":1,"maximum":10,"description":"How strictly the diffusion process adheres to the prompt text (higher values keep your image closer to your prompt). The _Large_ and _Medium_ models use a default of `4`. The _Turbo_ and _Flash_ model uses a default of `1`."}},"required":["prompt"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/control/sketch":{"post":{"tags":["Control"],"summary":"Sketch","description":"This service offers an ideal solution for design projects that require brainstorming and\nfrequent iterations. It upgrades rough hand-drawn sketches to refined outputs with precise\ncontrol. For non-sketch images, it allows detailed manipulation of the final appearance by\nleveraging the contour lines and edges within the image.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=ZKIAqHzJzzUo)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request should include:\n- `image`\n- `prompt`\n\nThe body may optionally include:\n- `control_strength`\n- `negative_prompt`\n- `seed`\n- `output_format`\n- `style_preset`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will match that of the input image.\n\n### Credits\nFlat rate of 5 credits per successful generation. You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/control/sketch\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./sketch.png\", \"rb\")\n    },\n    data={\n        \"prompt\": \"a medieval castle on a hill\",\n        \"control_strength\": 0.7,\n        \"output_format\": \"webp\"\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./castle.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import axios from \"axios\";\nimport FormData from \"form-data\";\nimport fs from \"node:fs\";\n\nconst payload = {\n    image: fs.createReadStream(\"./sketch.png\"),\n    prompt: \"a medieval castle on a hill\",\n    control_strength: 0.6,\n    output_format: \"webp\",\n};\n\nconst response = await axios.postForm(\n    `https://api.stability.ai/v2beta/stable-image/control/sketch`,\n    axios.toFormData(payload, new FormData()),\n    {\n        validateStatus: undefined,\n        responseType: \"arraybuffer\",\n        headers: {\n            Authorization: `Bearer sk-MYAPIKEY`,\n            Accept: \"image/*\"\n        },\n    },\n);\n\nif (response.status === 200) {\n    fs.writeFileSync(\"./castle.webp\", Buffer.from(response.data));\n} else {\n    throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/control/sketch\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./sketch.png\" \\\n  -F prompt=\"a medieval castle on a hill\" \\\n  -F control_strength=0.7 \\\n  -F output_format=\"webp\" \\\n  -o \"./castle.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"image":{"type":"string","description":"Supported Formats:\n- jpeg\n- png\n- webp\n\nImage Dimensions:\n- Every side must be at least 64 pixels\n- The total pixel count cannot exceed 9,437,184 pixels (e.g. 3072x3072, 4096x2304, etc.)\n\nImage Aspect Ratio:\n- Must be between 1:2.5 and 2.5:1 (i.e. cannot be too tall or too wide)","format":"binary","example":"./some/image.png"},"control_strength":{"type":"number","minimum":0,"maximum":1,"default":0.7,"description":"How much influence, or control, the `image` has on the generation. Represented as a float between 0 and 1, where 0 is the least influence and 1 is the maximum."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["png","jpeg","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."}},"required":["prompt","image"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/control/structure":{"post":{"tags":["Control"],"summary":"Structure","description":"This service excels in generating images by maintaining the structure of an input image,\nmaking it especially valuable for advanced content creation scenarios such as recreating\nscenes or rendering characters from models.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=59RaZazXz0AU)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request should include:\n- `image`\n- `prompt`\n\nThe body may optionally include:\n- `control_strength`\n- `negative_prompt`\n- `seed`\n- `output_format`\n- `style_preset`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will match that of the input image.\n\n### Credits\nFlat rate of 5 credits per successful generation. You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/control/structure\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./cat-statue.png\", \"rb\")\n    },\n    data={\n        \"prompt\": \"a well manicured shrub in an english garden\",\n        \"control_strength\": 0.7,\n        \"output_format\": \"webp\"\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./shrub-in-a-garden.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import axios from \"axios\";\nimport FormData from \"form-data\";\nimport fs from \"node:fs\";\n\nconst payload = {\n    image: fs.createReadStream(\"./cat-statue.png\"),\n    prompt: \"a well manicured shrub in an english garden\",\n    control_strength: 0.6,\n    output_format: \"webp\",\n};\n\nconst response = await axios.postForm(\n    `https://api.stability.ai/v2beta/stable-image/control/structure`,\n    axios.toFormData(payload, new FormData()),\n    {\n        validateStatus: undefined,\n        responseType: \"arraybuffer\",\n        headers: {\n            Authorization: `Bearer sk-MYAPIKEY`,\n            Accept: \"image/*\"\n        },\n    },\n);\n\nif (response.status === 200) {\n    fs.writeFileSync(\"./shrub-in-a-garden.webp\", Buffer.from(response.data));\n} else {\n    throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/control/structure\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./cat-statue.png\" \\\n  -F prompt=\"a well manicured shrub in an english garden\" \\\n  -F control_strength=0.7 \\\n  -F output_format=\"webp\" \\\n  -o \"./shrub-in-a-garden.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"image":{"type":"string","description":"An image whose structure you wish to use as the foundation for a generation.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels\n- The aspect ratio must be between 1:2.5 and 2.5:1","format":"binary","example":"./some/image.png"},"control_strength":{"type":"number","minimum":0,"maximum":1,"default":0.7,"description":"How much influence, or control, the `image` has on the generation. Represented as a float between 0 and 1, where 0 is the least influence and 1 is the maximum."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["png","jpeg","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."}},"required":["prompt","image"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/control/style":{"post":{"tags":["Control"],"summary":"Style Guide","description":"This service extracts stylistic elements from an input image (control image) and uses it to guide the creation of an output image based on the prompt. The result is a new image in the same style as the control image.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to [![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=y0WKjG72RvTE)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request should include:\n- `image`\n- `prompt`\n\nThe body may optionally include:\n- `negative_prompt`\n- `aspect_ratio`\n- `fidelity`\n- `seed`\n- `output_format`\n- `style_preset`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will be 1MP. The default resolution is 1024x1024.\n\n### Credits\nFlat rate of 5 credits per successful generation. You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/control/style\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"image\": open(\"./cinematic-portrait.png\", \"rb\")\n    },\n    data={\n        \"prompt\": \"a majestic portrait of a chicken\",\n        \"output_format\": \"webp\"\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./chicken-portrait.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import axios from \"axios\";\nimport FormData from \"form-data\";\nimport fs from \"node:fs\";\n\nconst payload = {\n    image: fs.createReadStream(\"./cinematic-portrait.png\"),\n    prompt: \"a majestic portrait of a chicken\",\n    output_format: \"webp\",\n};\n\nconst response = await axios.postForm(\n    `https://api.stability.ai/v2beta/stable-image/control/style`,\n    axios.toFormData(payload, new FormData()),\n    {\n        validateStatus: undefined,\n        responseType: \"arraybuffer\",\n        headers: {\n            Authorization: `Bearer sk-MYAPIKEY`,\n            Accept: \"image/*\"\n        },\n    },\n);\n\nif (response.status === 200) {\n    fs.writeFileSync(\"./chicken-portrait.webp\", Buffer.from(response.data));\n} else {\n    throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/control/style\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F image=@\"./cinematic-portrait.png\" \\\n  -F prompt=\"a majestic portrait of a chicken\" \\\n  -F output_format=\"webp\" \\\n  -o \"./chicken-portrait.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"image":{"type":"string","description":"An image whose style you wish to use as the foundation for a generation.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Every side must be at least 64 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels\n- The aspect ratio must be between 1:2.5 and 2.5:1","format":"binary","example":"./some/image.png"},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"aspect_ratio":{"type":"string","enum":["21:9","16:9","3:2","5:4","1:1","4:5","2:3","9:16","9:21"],"default":"1:1","description":"Controls the aspect ratio of the generated image."},"fidelity":{"type":"number","minimum":0,"maximum":1,"default":0.5,"description":"How closely the output image's style resembles the input image's style."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"output_format":{"type":"string","enum":["png","jpeg","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."},"style_preset":{"type":"string","enum":["enhance","anime","photographic","digital-art","comic-book","fantasy-art","line-art","analog-film","neon-punk","isometric","low-poly","origami","modeling-compound","cinematic","3d-model","pixel-art","tile-texture"],"description":"Guides the image model towards a particular style."}},"required":["prompt","image"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}},"/v2beta/stable-image/control/style-transfer":{"post":{"tags":["Control"],"summary":"Style Transfer","description":"Style Transfer applies visual characteristics from reference style images to target images.\nWhile Style Guide extracts stylistic elements from an input image (control image) and uses it\nto guide the creation of an output image based on the prompt, Style Transfer specifically\ntransforms existing content while preserving the original composition.\nThis tool helps create consistent content across multiple assets.\n\n### Try it out\nGrab your [API key](https://platform.stability.ai/account/keys) and head over to\n[![Open Google Colab](https://platform.stability.ai/svg/google-colab.svg)](https://colab.research.google.com/github/stability-ai/stability-sdk/blob/main/nbs/Stable_Image_API_Public.ipynb#scrollTo=YCrxdv5LzqJ9)\n\n### How to use\nPlease invoke this endpoint with a `POST` request.\n\nThe headers of the request must include an API key in the `authorization` field. The body of the request must be\n`multipart/form-data`, and the `accept` header should be set to one of the following:\n  - `image/*` to receive the image in the format specified by the `output_format` parameter.\n  - `application/json` to receive the image encoded as base64 in a JSON response.\n\nThe body of the request should include:\n- `init_image`\n- `style_image`\n\nThe body may optionally include:\n- `prompt`\n- `negative_prompt`\n- `style_strength`\n- `composition_fidelity`\n- `change_strength`\n- `seed`\n- `output_format`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\n### Output\nThe resolution of the generated image will be 1MP, with the same aspect ratio as the `init_image`.\n\n### Credits\nFlat rate of 8 credits per successful generation. You will not be charged for failed generations.","x-codeSamples":[{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.post(\n    f\"https://api.stability.ai/v2beta/stable-image/control/style-transfer\",\n    headers={\n        \"authorization\": f\"Bearer sk-MYAPIKEY\",\n        \"accept\": \"image/*\"\n    },\n    files={\n        \"init_image\": open(\"./chicken-portrait.png\", \"rb\"),\n        \"style_image\": open(\"./glowbot.png\", \"rb\")\n    },\n    data={\n        \"output_format\": \"webp\"\n    },\n)\n\nif response.status_code == 200:\n    with open(\"./glow-chicken.webp\", 'wb') as file:\n        file.write(response.content)\nelse:\n    raise Exception(str(response.json()))"},{"lang":"javascript","label":"JavaScript","source":"import axios from \"axios\";\nimport FormData from \"form-data\";\nimport fs from \"node:fs\";\n\nconst payload = {\n    init_image: fs.createReadStream(\"./chicken-portrait.png\"),\n    style_image: fs.createReadStream(\"./glowbot.png\"),\n    output_format: \"webp\",\n};\n\nconst response = await axios.postForm(\n    `https://api.stability.ai/v2beta/stable-image/control/style-transfer`,\n    axios.toFormData(payload, new FormData()),\n    {\n        validateStatus: undefined,\n        responseType: \"arraybuffer\",\n        headers: {\n            Authorization: `Bearer sk-MYAPIKEY`,\n            Accept: \"image/*\"\n        },\n    },\n);\n\nif (response.status === 200) {\n    fs.writeFileSync(\"./glow-chicken.webp\", Buffer.from(response.data));\n} else {\n    throw new Error(`${response.status}: ${response.data.toString()}`);\n}"},{"lang":"terminal","label":"cURL","source":"curl -f -sS \"https://api.stability.ai/v2beta/stable-image/control/style-transfer\" \\\n  -H \"authorization: Bearer sk-MYAPIKEY\" \\\n  -H \"accept: image/*\" \\\n  -F init_image=@\"./chicken-portrait.png\" \\\n  -F style_image=@\"./glowbot.png\" \\\n  -F output_format=\"webp\" \\\n  -o \"./glow-chicken.webp\""}],"parameters":[{"schema":{"type":"string","description":"Your [Stability API key](https://platform.stability.ai/account/keys), used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.","minLength":1},"required":true,"name":"authorization","in":"header"},{"schema":{"type":"string","minLength":1,"description":"The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.","example":"multipart/form-data"},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"string","default":"image/*","description":"Specify `image/*` to receive the bytes of the image directly. Otherwise specify `application/json` to receive the image as base64 encoded JSON.","enum":["image/*","application/json"]},"required":false,"name":"accept","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientID"},"required":false,"name":"stability-client-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientUserID"},"required":false,"name":"stability-client-user-id","in":"header"},{"schema":{"$ref":"#/components/schemas/StabilityClientVersion"},"required":false,"name":"stability-client-version","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"init_image":{"type":"string","description":"An image containing the subject you wish to restyle.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Width must be between 64 and 16,383 pixels\n- Height must be between 64 and 16,383 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels\n- The aspect ratio must be between 1:2.5 and 2.5:1","format":"binary","example":"./some/image.png"},"style_image":{"type":"string","description":"An image containing the new style.\n\nSupported Formats:\n- jpeg\n- png\n- webp\n\nValidation Rules:\n- Width must be between 64 and 16,383 pixels\n- Height must be between 64 and 16,383 pixels\n- Total pixel count must be between 4,096 and 9,437,184 pixels","format":"binary","example":"./some/image.png"},"prompt":{"type":"string","minLength":0,"maxLength":10000,"description":"What you wish to see in the output image. A strong, descriptive prompt that clearly defines\nelements, colors, and subjects will lead to better results.\n\nTo control the weight of a given word use the format `(word:weight)`,\nwhere `word` is the word you'd like to control the weight of and `weight`\nis a value between 0 and 1. For example: `The sky was a crisp (blue:0.3) and (green:0.8)`\nwould convey a sky that was blue and green, but more green than blue."},"negative_prompt":{"type":"string","maxLength":10000,"description":"A blurb of text describing what you **do not** wish to see in the output image.\nThis is an advanced feature."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass `0` to use a random seed.)"},"style_strength":{"type":"number","minimum":0,"maximum":1,"default":1,"description":"Sometimes referred to as _denoising_, this parameter controls how much influence the\n`style_image` parameter has on the generated image. A value of 0 would yield an image that\nis identical to the input. A value of 1 would be as if you passed in no image at all."},"composition_fidelity":{"type":"number","minimum":0,"maximum":1,"default":0.9,"description":"How closely the output image's style resembles the input image's style."},"change_strength":{"type":"number","minimum":0.1,"maximum":1,"default":0.9,"description":"How much the original image should change"},"output_format":{"type":"string","enum":["png","jpeg","webp"],"default":"png","description":"Dictates the `content-type` of the generated image."}},"required":["init_image","style_image"]}}}},"responses":{"200":{"description":"Generation was successful.","headers":{"x-request-id":{"description":"A unique identifier for this request.","schema":{"type":"string"}},"content-type":{"description":"The format of the generated image.\n\n To receive the bytes of the image directly, specify `image/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.","examples":{"png":{"description":"raw bytes","value":"image/png"},"pngJSON":{"description":"base64 encoded","value":"application/json; type=image/png"},"jpeg":{"description":"raw bytes","value":"image/jpeg"},"jpegJSON":{"description":"base64 encoded","value":"application/json; type=image/jpeg"},"webp":{"description":"raw bytes","value":"image/webp"},"webpJSON":{"description":"base64 encoded","value":"application/json; type=image/webp"}},"schema":{"type":"string"}},"finish-reason":{"schema":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"]},"description":"Indicates the reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `finish_reason`."},"seed":{"description":"The seed used as random noise for this generation.\n\n> **NOTE:** This header is absent on JSON encoded responses because it is present in the body as `seed`.","example":"343940597","schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated png"},"application/json; type=image/png":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/jpeg":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated jpeg"},"application/json; type=image/jpeg":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}},"image/webp":{"schema":{"type":"string","description":"The bytes of the generated image.\n\nThe `finish-reason` and `seed` will be present as headers.","format":"binary"},"example":"The bytes of the generated webp"},"application/json; type=image/webp":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The generated image, encoded to base64.","example":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..."},"seed":{"type":"number","minimum":0,"maximum":4294967294,"default":0,"description":"The seed used as random noise for this generation.","example":343940597},"finish_reason":{"type":"string","enum":["SUCCESS","CONTENT_FILTERED"],"description":"The reason the generation finished.\n\n- `SUCCESS` = successful generation.\n- `CONTENT_FILTERED` = successful generation, however the output violated our content moderation\npolicy and has been blurred as a result.","example":"SUCCESS"}},"required":["image","finish_reason"]}}}},"400":{"description":"Invalid parameter(s), see the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]}}}},"403":{"description":"Your request was flagged by our content moderation system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentModerationResponse"}}}},"413":{"description":"Your request was larger than 10MiB.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"4212a4b66fbe1cedca4bf2133d35dca5","name":"payload_too_large","errors":["body: payloads cannot be larger than 10MiB in size"]}}}}},"422":{"description":"Your request was well-formed, but rejected. See the `errors` field for details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"]},"examples":{"Invalid Language":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"invalid_language","errors":["English is the only supported language for this service."]}},"Public Figure Detected":{"value":{"id":"ff54b236a3acdde1522cb1ba641c43ed","name":"public_figure","errors":["Our system detected the likeness of a public figure in your image. To comply with our guidelines, this request cannot be processed. Please upload a different image."]}}}}}},"429":{"description":"You have made more than 150 requests in 10 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"rate_limit_exceeded","name":"rate_limit_exceeded","errors":["You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."]}}}}},"500":{"description":"An internal error occurred. If the problem persists [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"A unique identifier associated with this error. Please include this in any [support tickets](https://kb.stability.ai/knowledge-base/kb-tickets/new)\nyou file, as it will greatly assist us in diagnosing the root cause of the problem.","example":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},"name":{"type":"string","minLength":1,"description":"Short-hand name for an error, useful for discriminating between errors with the same status code.","example":"bad_request"},"errors":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more error messages indicating what went wrong.","example":["some-field: is required"]}},"required":["id","name","errors"],"example":{"id":"2a1b2d4eafe2bc6ab4cd4d5c6133f513","name":"internal_error","errors":["An unexpected server error has occurred, please try again later."]}}}}}}}}}}