{ "openapi": "3.0.3", "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://stabilityplatform.freshdesk.com/support/home).\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://stabilityplatform.freshdesk.com/support/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 & 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": "User", "description": "Manage your Stability account, and view account/organization balances." }, { "name": "Engines", "description": "Enumerate engines that work with 'Version 1' REST API endpoints." }, { "name": "SDXL 1.0 & SD1.6", "description": "Generate images using SDXL 1.0 or SD1.6." } ], "paths": { "/v2alpha/generation/image-to-video": { "post": { "tags": [ "v2alpha/generation" ], "summary": "image-to-video", "description": "Generate a short video based on an initial image with [Stable Video Diffusion](https://static1.squarespace.com/static/6213c340453c3f502425776e/t/655ce779b9d47d342a93c890/1700587395994/stable_video_diffusion.pdf),\na latent video diffusion model. \n\n\n\n### How to generate a video\nVideo generations are asynchronous, so after starting a generation use the `id` returned in the response to poll [/v2alpha/generation/image-to-video/result/{id}](#tag/v2alphageneration/paths/~1v2alpha~1generation~1image-to-video~1result~1%7Bid%7D/get) for results.\n\n### Price\nFlat rate of 20 cents per generation.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "import requests\n\nresponse = requests.post(\n f\"https://api.stability.ai/v2alpha/generation/image-to-video\",\n headers={\"authorization\": f\"Bearer sk-MYAPIKEY\"},\n files={\"image\": open(\"./kittens-in-space.png\", \"rb\")},\n data={\n \"seed\": 0,\n \"cfg_scale\": 1.8,\n \"motion_bucket_id\": 127\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 data = new FormData();\ndata.append(\"image\", fs.readFileSync(\"./image.png\"), \"image.png\");\ndata.append(\"seed\", 0);\ndata.append(\"cfg_scale\", 1.8);\ndata.append(\"motion_bucket_id\", 127);\n\nconst response = await axios.request({\n url: `https://api.stability.ai/v2alpha/generation/image-to-video`,\n method: \"post\",\n validateStatus: undefined,\n headers: {\n authorization: `Bearer sk-MYAPIKEY`,\n ...data.getHeaders(),\n },\n data: data,\n});\n\nconsole.log(\"Generation ID:\", response.data.id);" }, { "lang": "terminal", "label": "cURL", "source": "curl -f -sS \"https://api.stability.ai/v2alpha/generation/image-to-video\" \\\n -H \"authorization: Bearer sk-MYAPIKEY\" \\\n -F image=@\"./image.png\" \\\n -F seed=0 \\\n -F cfg_scale=1.8 \\\n -F motion_bucket_id=127 \\\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": { "$ref": "#/components/schemas/ImageToVideoRequest" } } } }, "responses": { "200": { "description": "Video generation started. Poll for results using the `id` in the response [here](#tag/v2alphageneration/paths/~1v2alpha~1generation~1image-to-video~1result~1%7Bid%7D/get).", "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://stabilityplatform.freshdesk.com/support/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" ] } } } }, "500": { "description": "An internal error occurred. If the problem persists [contact support](https://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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/image-to-video/result/{id}": { "get": { "tags": [ "v2alpha/generation" ], "summary": "image-to-video/result", "description": "Fetch the result of an image-to-video generation by ID. Make sure you use the same API key that you used to\ngenerate the video, 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 and you will need to \nre-generate your video.", "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/image-to-video/result/{generation_id}\",\n headers={\n 'Accept': \"video/*\", # 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(\"video.mp4\", '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/image-to-video/result/${generationID}`,\n method: \"GET\",\n validateStatus: undefined,\n responseType: \"arraybuffer\",\n headers: {\n accept: \"video/*\", // 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(\"video.mp4\", 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/image-to-video/result/$generation_id\"\nhttp_status=$(curl -sS -f -o \"./output.mp4\" -w '%{http_code}' -H \"authorization: sk-MYAPIKEY\" -H 'accept: video/*' \"$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 \"./output.mp4\" \"./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": "video/*", "description": "Specify `video/*` to get the video bytes directly. Otherwise specify `application/json` to receive the video as base64 encoded JSON.", "enum": [ "video/*", "application/json" ] }, "required": false, "name": "accept", "in": "header" } ], "responses": { "200": { "description": "The result of your video generation.", "headers": { "x-request-id": { "description": "A unique identifier for this request.", "schema": { "type": "string" } }, "content-type": { "description": "The format of the generated video.\n\n To receive the bytes of the video directly, specify `video/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.", "examples": { "mp4": { "description": "raw bytes", "value": "video/mp4" }, "mp4JSON": { "description": "base64 encoded", "value": "application/json; type=video/mp4" } }, "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 one or more frames have 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": { "video/mp4": { "schema": { "type": "string", "description": "The bytes of the generated video.\n\nThe `finish-reason` and `seed` will be present as headers.", "format": "binary" }, "example": "The bytes of the generated mp4.\n(Caution: may contain cats)" }, "application/json; type=video/mp4": { "schema": { "type": "object", "properties": { "video": { "type": "string", "description": "The generated video, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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 one or more frames have been blurred as a result.", "example": "SUCCESS" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "required": [ "video", "finish_reason" ] } } } }, "202": { "description": "Your image-to-video 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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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": { "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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/image-to-video": { "post": { "tags": [ "Image-to-Video" ], "summary": "Start generation", "description": "Generate a short video based on an initial image with [Stable Video Diffusion](https://static1.squarespace.com/static/6213c340453c3f502425776e/t/655ce779b9d47d342a93c890/1700587395994/stable_video_diffusion.pdf),\na latent video diffusion model. \n\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\nThe body may optionally include:\n- `seed`\n- `cfg_scale`\n- `motion_bucket_id`\n\n> **Note:** for more details about these parameters please see the request schema below.\n\nAfter invoking this endpoint with the required parameters, use the `id` in the response to poll for results at the\n[image-to-video/result/{id}](#tag/Image-to-Video/paths/~1v2beta~1image-to-video~1result~1%7Bid%7D/get) endpoint. Rate-limiting or other errors may occur if you poll more than once every 10 seconds.\n\n### Credits\nFlat rate of 20 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/image-to-video\",\n headers={\n \"authorization\": f\"Bearer sk-MYAPIKEY\"\n },\n files={\n \"image\": open(\"./kittens-in-space.png\", \"rb\")\n },\n data={\n \"seed\": 0,\n \"cfg_scale\": 1.8,\n \"motion_bucket_id\": 127\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 data = new FormData();\ndata.append(\"image\", fs.readFileSync(\"./image.png\"), \"image.png\");\ndata.append(\"seed\", 0);\ndata.append(\"cfg_scale\", 1.8);\ndata.append(\"motion_bucket_id\", 127);\n\nconst response = await axios.request({\n url: `https://api.stability.ai/v2beta/image-to-video`,\n method: \"post\",\n validateStatus: undefined,\n headers: {\n authorization: `Bearer sk-MYAPIKEY`,\n ...data.getHeaders(),\n },\n data: data,\n});\n\nconsole.log(\"Generation ID:\", response.data.id);" }, { "lang": "terminal", "label": "cURL", "source": "curl -f -sS \"https://api.stability.ai/v2beta/image-to-video\" \\\n -H \"authorization: Bearer sk-MYAPIKEY\" \\\n -F image=@\"./image.png\" \\\n -F seed=0 \\\n -F cfg_scale=1.8 \\\n -F motion_bucket_id=127 \\\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": { "$ref": "#/components/schemas/ImageToVideoRequest" } } } }, "responses": { "200": { "description": "Video generation started. Poll for results using the `id` in the response [here](#tag/Image-to-Video/paths/~1v2beta~1image-to-video~1result~1%7Bid%7D/get).", "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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/image-to-video/result/{id}": { "get": { "tags": [ "Image-to-Video" ], "summary": "Fetch generation result", "description": "Fetch the result of an image-to-video 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 and you will need to \nre-generate your video.", "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/image-to-video/result/{generation_id}\",\n headers={\n 'accept': \"video/*\", # 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(\"video.mp4\", '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/image-to-video/result/${generationID}`,\n method: \"GET\",\n validateStatus: undefined,\n responseType: \"arraybuffer\",\n headers: {\n Authorization: `Bearer sk-MYAPIKEY`,\n Accept: \"video/*\", // 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(\"video.mp4\", 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/image-to-video/result/$generation_id\"\nhttp_status=$(curl -sS -f -o \"./output.mp4\" -w '%{http_code}' -H \"authorization: sk-MYAPIKEY\" -H 'accept: video/*' \"$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 \"./output.mp4\" \"./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": "video/*", "description": "Specify `video/*` to receive the bytes of the video directly. Otherwise specify `application/json` to receive the video as base64 encoded JSON.", "enum": [ "video/*", "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": "The result of your video generation.", "headers": { "x-request-id": { "description": "A unique identifier for this request.", "schema": { "type": "string" } }, "content-type": { "description": "The format of the generated video.\n\n To receive the bytes of the video directly, specify `video/*` in the accept header. To receive the bytes base64 encoded inside of a JSON payload, specify `application/json`.", "examples": { "mp4": { "description": "raw bytes", "value": "video/mp4" }, "mp4JSON": { "description": "base64 encoded", "value": "application/json; type=video/mp4" } }, "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 one or more frames have 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": { "video/mp4": { "schema": { "type": "string", "description": "The bytes of the generated video.\n\nThe `finish-reason` and `seed` will be present as headers.", "format": "binary" }, "example": "The bytes of the generated mp4.\n(Caution: may contain cats)" }, "application/json; type=video/mp4": { "schema": { "type": "object", "properties": { "video": { "type": "string", "description": "The generated video, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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 one or more frames have been blurred as a result.", "example": "SUCCESS" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "required": [ "video", "finish_reason" ] } } } }, "202": { "description": "Your image-to-video 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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 2 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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 25 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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 25 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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 1 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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 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/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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 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/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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 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/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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 2 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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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.0 & 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\nRead more about the model capabilities [here](https://stability.ai/news/introducing-stable-diffusion-3-5).\n\nStable Diffusion 3.0 models are also supported, powered by [Fireworks AI](https://fireworks.ai/). API status can be reviewed [here](https://readme.fireworks.ai/page/application-status).\n\n- **SD3 Large**: the 8 billion parameter model\n- **SD3 Large Turbo**: the 8 billion parameter model with a faster inference time\n- **SD3 Medium**: the 2 billion parameter model\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 (SD3.5 Large, SD3.5 Large Turbo, etc.)\n- `output_format` - the 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 & 3.0 Large**: Flat rate of 6.5 credits per successful generation.\n- **SD 3.5 & 3.0 Large Turbo**: Flat rate of 4 credits per successful generation.\n- **SD 3.5 & 3.0 Medium**: Flat rate of 3.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." }, "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", "sd3-medium", "sd3-large", "sd3-large-turbo" ], "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-large` requires 6.5 credits per generation\n- `sd3-large-turbo` requires 4 credits per generation\n- `sd3-medium` requires 3.5 credits per generation" }, "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" ], "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.\n\n> **Important:** This parameter has no effect on the `sd3-*` models." }, "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.\n\n> **Important:** This parameter does **not** work with `sd3-large-turbo`." }, "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)." } }, "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" } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 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/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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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 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/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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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", "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 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/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.\n(Caution: may contain cats)" }, "application/json; type=image/png": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/jpeg": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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.\n(Caution: may contain cats)" }, "application/json; type=image/webp": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The generated image, encoded to base64.", "example": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1..." }, "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" }, "seed": { "type": "number", "minimum": 0, "maximum": 4294967294, "default": 0, "description": "The seed used as random noise for this generation.", "example": 343940597 } }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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." ] } } } } } } } }, "/v1/generation/{engine_id}/text-to-image": { "post": { "description": "Generate an image from a text prompt. \n### Using SDXL 1.0\nUse `stable-diffusion-xl-1024-v1-0` as the `engine_id` of your request and pass in `height` & `width` as one of the following combinations:\n- 1024x1024 (default)\n- 1152x896\n- 896x1152\n- 1216x832\n- 1344x768\n- 768x1344\n- 1536x640\n- 640x1536 \n\n### SDXL 1.0 Pricing\nWhen specifying 30 steps or fewer, generation costs 0.9 credits.\n\nWhen specifying above 30 steps, generation cost is determined using the following formula:\n\n `cost = 0.9 * (steps / 30)`\n\n### Using SD 1.6\nSD1.6 is a flexible-resolution base model allowing you to generate non-standard aspect ratios. The model is optimized for a resolution of 512 x 512 pixels. To generate 1 megapixel outputs, we recommend using SDXL 1.0, which is available at the same price.\n\nPass in `stable-diffusion-v1-6` as the `engine_id` of your request and ensure the `height` & `width` you pass in adhere to the following restrictions:\n- No dimension can be less than 320 pixels\n- No dimension can be greater than 1536 pixels\n- Height and width must be specified in increments of 64\n- The default resolution is 512 x 512\n", "operationId": "textToImage", "summary": "Text-to-image", "tags": [ "SDXL 1.0 & SD1.6" ], "parameters": [ { "$ref": "#/components/parameters/engineID" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/organization" }, { "$ref": "#/components/parameters/stabilityClientID" }, { "$ref": "#/components/parameters/stabilityClientVersion" } ], "requestBody": { "content": { "application/json": { "example": { "cfg_scale": 7, "height": 512, "width": 512, "sampler": "K_DPM_2_ANCESTRAL", "samples": 1, "steps": 30, "text_prompts": [ { "text": "A lighthouse on a cliff", "weight": 1 } ] }, "schema": { "$ref": "#/components/schemas/TextToImageRequestBody" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/GenerationResponse" }, "400": { "$ref": "#/components/responses/400FromGeneration" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "STABILITY_API_KEY": [] } ], "x-codeSamples": [ { "lang": "Python", "source": "import base64\nimport os\nimport requests\n\nengine_id = \"stable-diffusion-v1-6\"\napi_host = os.getenv('API_HOST', 'https://api.stability.ai')\napi_key = os.getenv(\"STABILITY_API_KEY\")\n\nif api_key is None:\n raise Exception(\"Missing Stability API key.\")\n\nresponse = requests.post(\n f\"{api_host}/v1/generation/{engine_id}/text-to-image\",\n headers={\n \"Content-Type\": \"application/json\",\n \"Accept\": \"application/json\",\n \"Authorization\": f\"Bearer {api_key}\"\n },\n json={\n \"text_prompts\": [\n {\n \"text\": \"A lighthouse on a cliff\"\n }\n ],\n \"cfg_scale\": 7,\n \"height\": 1024,\n \"width\": 1024,\n \"samples\": 1,\n \"steps\": 30,\n },\n)\n\nif response.status_code != 200:\n raise Exception(\"Non-200 response: \" + str(response.text))\n\ndata = response.json()\n\nfor i, image in enumerate(data[\"artifacts\"]):\n with open(f\"./out/v1_txt2img_{i}.png\", \"wb\") as f:\n f.write(base64.b64decode(image[\"base64\"]))\n" }, { "label": "TypeScript", "lang": "Javascript", "source": "import fetch from 'node-fetch'\nimport fs from 'node:fs'\n\nconst engineId = 'stable-diffusion-v1-6'\nconst apiHost = process.env.API_HOST ?? 'https://api.stability.ai'\nconst apiKey = process.env.STABILITY_API_KEY\n\nif (!apiKey) throw new Error('Missing Stability API key.')\n\nconst response = await fetch(\n `${apiHost}/v1/generation/${engineId}/text-to-image`,\n {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n Accept: 'application/json',\n Authorization: `Bearer ${apiKey}`,\n },\n body: JSON.stringify({\n text_prompts: [\n {\n text: 'A lighthouse on a cliff',\n },\n ],\n cfg_scale: 7,\n height: 1024,\n width: 1024,\n steps: 30,\n samples: 1,\n }),\n }\n)\n\nif (!response.ok) {\n throw new Error(`Non-200 response: ${await response.text()}`)\n}\n\ninterface GenerationResponse {\n artifacts: Array<{\n base64: string\n seed: number\n finishReason: string\n }>\n}\n\nconst responseJSON = (await response.json()) as GenerationResponse\n\nresponseJSON.artifacts.forEach((image, index) => {\n fs.writeFileSync(\n `./out/v1_txt2img_${index}.png`,\n Buffer.from(image.base64, 'base64')\n )\n})\n" }, { "lang": "Go", "source": "package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/base64\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n)\n\ntype TextToImageImage struct {\n\tBase64 string `json:\"base64\"`\n\tSeed uint32 `json:\"seed\"`\n\tFinishReason string `json:\"finishReason\"`\n}\n\ntype TextToImageResponse struct {\n\tImages []TextToImageImage `json:\"artifacts\"`\n}\n\nfunc main() {\n\t// Build REST endpoint URL w/ specified engine\n\tengineId := \"stable-diffusion-v1-6\"\n\tapiHost, hasApiHost := os.LookupEnv(\"API_HOST\")\n\tif !hasApiHost {\n\t\tapiHost = \"https://api.stability.ai\"\n\t}\n\treqUrl := apiHost + \"/v1/generation/\" + engineId + \"/text-to-image\"\n\n\t// Acquire an API key from the environment\n\tapiKey, hasAPIKey := os.LookupEnv(\"STABILITY_API_KEY\")\n\tif !hasAPIKey {\n\t\tpanic(\"Missing STABILITY_API_KEY environment variable\")\n\t}\n\n\tvar data = []byte(`{\n\t\t\"text_prompts\": [\n\t\t {\n\t\t\t\"text\": \"A lighthouse on a cliff\"\n\t\t }\n\t\t],\n\t\t\"cfg_scale\": 7,\n\t\t\"height\": 1024,\n\t\t\"width\": 1024,\n\t\t\"samples\": 1,\n\t\t\"steps\": 30\n \t}`)\n\n\treq, _ := http.NewRequest(\"POST\", reqUrl, bytes.NewBuffer(data))\n\treq.Header.Add(\"Content-Type\", \"application/json\")\n\treq.Header.Add(\"Accept\", \"application/json\")\n\treq.Header.Add(\"Authorization\", \"Bearer \"+apiKey)\n\n\t// Execute the request & read all the bytes of the body\n\tres, _ := http.DefaultClient.Do(req)\n\tdefer res.Body.Close()\n\n\tif res.StatusCode != 200 {\n\t\tvar body map[string]interface{}\n\t\tif err := json.NewDecoder(res.Body).Decode(&body); err != nil {\n\t\t\tpanic(err)\n\t\t}\n\t\tpanic(fmt.Sprintf(\"Non-200 response: %s\", body))\n\t}\n\n\t// Decode the JSON body\n\tvar body TextToImageResponse\n\tif err := json.NewDecoder(res.Body).Decode(&body); err != nil {\n\t\tpanic(err)\n\t}\n\n\t// Write the images to disk\n\tfor i, image := range body.Images {\n\t\toutFile := fmt.Sprintf(\"./out/v1_txt2img_%d.png\", i)\n\t\tfile, err := os.Create(outFile)\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\timageBytes, err := base64.StdEncoding.DecodeString(image.Base64)\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tif _, err := file.Write(imageBytes); err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tif err := file.Close(); err != nil {\n\t\t\tpanic(err)\n\t\t}\n\t}\n}\n" }, { "lang": "cURL", "source": "if [ -z \"$STABILITY_API_KEY\" ]; then\n echo \"STABILITY_API_KEY environment variable is not set\"\n exit 1\nfi\n\nOUTPUT_FILE=./out/v1_txt2img.png\nBASE_URL=${API_HOST:-https://api.stability.ai}\nURL=\"$BASE_URL/v1/generation/stable-diffusion-v1-6/text-to-image\"\n\ncurl -f -sS -X POST \"$URL\" \\\n -H 'Content-Type: application/json' \\\n -H 'Accept: image/png' \\\n -H \"Authorization: Bearer $STABILITY_API_KEY\" \\\n --data-raw '{\n \"text_prompts\": [\n {\n \"text\": \"A lighthouse on a cliff\"\n }\n ],\n \"cfg_scale\": 7,\n \"height\": 1024,\n \"width\": 1024,\n \"samples\": 1,\n \"steps\": 30\n }' \\\n -o \"$OUTPUT_FILE\"\n" } ] } }, "/v1/generation/{engine_id}/image-to-image": { "post": { "description": "Produce an image from an existing image using a text prompt. \n### How to control strength of generation\nTo preserve only roughly 35% of the initial image, pass in either `init_image_mode=IMAGE_STRENGTH` and `image_strength=0.35` or `init_image_mode=STEP_SCHEDULE` and `step_schedule_start=0.65`. Both of these are equivalent, however `init_image_mode=STEP_SCHEDULE` also lets you pass in `step_schedule_end`, which can provide an extra level of control for those who need it. For more details, see the specific fields below. \n\n> NOTE: Only **Version 1** engines will work with this endpoint.", "operationId": "imageToImage", "summary": "Image-to-image with prompt", "tags": [ "SDXL 1.0 & SD1.6" ], "parameters": [ { "$ref": "#/components/parameters/engineID" }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/organization" }, { "$ref": "#/components/parameters/stabilityClientID" }, { "$ref": "#/components/parameters/stabilityClientVersion" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageToImageRequestBody" }, "examples": { "IMAGE_STRENGTH": { "summary": "Using IMAGE_STRENGTH", "description": "Request using 35% image_strength", "value": { "image_strength": 0.35, "init_image_mode": "IMAGE_STRENGTH", "init_image": "", "text_prompts[0][text]": "A dog space commander", "text_prompts[0][weight]": 1, "cfg_scale": 7, "sampler": "K_DPM_2_ANCESTRAL", "samples": 3, "steps": 30 } }, "STEP_SCHEDULE": { "summary": "Using STEP_SCHEDULE", "description": "Equivalent request using step_schedule_start", "value": { "step_schedule_start": 0.65, "init_image_mode": "STEP_SCHEDULE", "init_image": "", "text_prompts[0][text]": "A dog space commander", "text_prompts[0][weight]": 1, "cfg_scale": 7, "sampler": "K_DPM_2_ANCESTRAL", "samples": 3, "steps": 30 } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/GenerationResponse" }, "400": { "$ref": "#/components/responses/400FromGeneration" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "STABILITY_API_KEY": [] } ], "x-codeSamples": [ { "lang": "Python", "source": "import base64\nimport os\nimport requests\n\nengine_id = \"stable-diffusion-v1-6\"\napi_host = os.getenv(\"API_HOST\", \"https://api.stability.ai\")\napi_key = os.getenv(\"STABILITY_API_KEY\")\n\nif api_key is None:\n raise Exception(\"Missing Stability API key.\")\n\nresponse = requests.post(\n f\"{api_host}/v1/generation/{engine_id}/image-to-image\",\n headers={\n \"Accept\": \"application/json\",\n \"Authorization\": f\"Bearer {api_key}\"\n },\n files={\n \"init_image\": open(\"../init_image.png\", \"rb\")\n },\n data={\n \"image_strength\": 0.35,\n \"init_image_mode\": \"IMAGE_STRENGTH\",\n \"text_prompts[0][text]\": \"Galactic dog with a cape\",\n \"cfg_scale\": 7,\n \"samples\": 1,\n \"steps\": 30,\n }\n)\n\nif response.status_code != 200:\n raise Exception(\"Non-200 response: \" + str(response.text))\n\ndata = response.json()\n\nfor i, image in enumerate(data[\"artifacts\"]):\n with open(f\"./out/v1_img2img_{i}.png\", \"wb\") as f:\n f.write(base64.b64decode(image[\"base64\"]))\n" }, { "label": "TypeScript", "lang": "Javascript", "source": "import fetch from 'node-fetch'\nimport FormData from 'form-data'\nimport fs from 'node:fs'\n\nconst engineId = 'stable-diffusion-v1-6'\nconst apiHost = process.env.API_HOST ?? 'https://api.stability.ai'\nconst apiKey = process.env.STABILITY_API_KEY\n\nif (!apiKey) throw new Error('Missing Stability API key.')\n\n// NOTE: This example is using a NodeJS FormData library.\n// Browsers should use their native FormData class.\n// React Native apps should also use their native FormData class.\nconst formData = new FormData()\nformData.append('init_image', fs.readFileSync('../init_image.png'))\nformData.append('init_image_mode', 'IMAGE_STRENGTH')\nformData.append('image_strength', 0.35)\nformData.append('text_prompts[0][text]', 'Galactic dog wearing a cape')\nformData.append('cfg_scale', 7)\nformData.append('samples', 1)\nformData.append('steps', 30)\n\nconst response = await fetch(\n `${apiHost}/v1/generation/${engineId}/image-to-image`,\n {\n method: 'POST',\n headers: {\n ...formData.getHeaders(),\n Accept: 'application/json',\n Authorization: `Bearer ${apiKey}`,\n },\n body: formData,\n }\n)\n\nif (!response.ok) {\n throw new Error(`Non-200 response: ${await response.text()}`)\n}\n\ninterface GenerationResponse {\n artifacts: Array<{\n base64: string\n seed: number\n finishReason: string\n }>\n}\n\nconst responseJSON = (await response.json()) as GenerationResponse\n\nresponseJSON.artifacts.forEach((image, index) => {\n fs.writeFileSync(\n `out/v1_img2img_${index}.png`,\n Buffer.from(image.base64, 'base64')\n )\n})\n" }, { "lang": "Go", "source": "package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/base64\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io\"\n\t\"mime/multipart\"\n\t\"net/http\"\n\t\"os\"\n)\n\ntype ImageToImageImage struct {\n\tBase64 string `json:\"base64\"`\n\tSeed uint32 `json:\"seed\"`\n\tFinishReason string `json:\"finishReason\"`\n}\n\ntype ImageToImageResponse struct {\n\tImages []ImageToImageImage `json:\"artifacts\"`\n}\n\nfunc main() {\n\tengineId := \"stable-diffusion-v1-6\"\n\n\t// Build REST endpoint URL\n\tapiHost, hasApiHost := os.LookupEnv(\"API_HOST\")\n\tif !hasApiHost {\n\t\tapiHost = \"https://api.stability.ai\"\n\t}\n\treqUrl := apiHost + \"/v1/generation/\" + engineId + \"/image-to-image\"\n\n\t// Acquire an API key from the environment\n\tapiKey, hasAPIKey := os.LookupEnv(\"STABILITY_API_KEY\")\n\tif !hasAPIKey {\n\t\tpanic(\"Missing STABILITY_API_KEY environment variable\")\n\t}\n\n\tdata := &bytes.Buffer{}\n\twriter := multipart.NewWriter(data)\n\n\t// Write the init image to the request\n\tinitImageWriter, _ := writer.CreateFormField(\"init_image\")\n\tinitImageFile, initImageErr := os.Open(\"../init_image.png\")\n\tif initImageErr != nil {\n\t\tpanic(\"Could not open init_image.png\")\n\t}\n\t_, _ = io.Copy(initImageWriter, initImageFile)\n\n\t// Write the options to the request\n\t_ = writer.WriteField(\"init_image_mode\", \"IMAGE_STRENGTH\")\n\t_ = writer.WriteField(\"image_strength\", \"0.35\")\n\t_ = writer.WriteField(\"text_prompts[0][text]\", \"Galactic dog with a cape\")\n\t_ = writer.WriteField(\"cfg_scale\", \"7\")\n\t_ = writer.WriteField(\"samples\", \"1\")\n\t_ = writer.WriteField(\"steps\", \"30\")\n\twriter.Close()\n\n\t// Execute the request\n\tpayload := bytes.NewReader(data.Bytes())\n\treq, _ := http.NewRequest(\"POST\", reqUrl, payload)\n\treq.Header.Add(\"Content-Type\", writer.FormDataContentType())\n\treq.Header.Add(\"Accept\", \"application/json\")\n\treq.Header.Add(\"Authorization\", \"Bearer \"+apiKey)\n\tres, _ := http.DefaultClient.Do(req)\n\tdefer res.Body.Close()\n\n\tif res.StatusCode != 200 {\n\t\tvar body map[string]interface{}\n\t\tif err := json.NewDecoder(res.Body).Decode(&body); err != nil {\n\t\t\tpanic(err)\n\t\t}\n\t\tpanic(fmt.Sprintf(\"Non-200 response: %s\", body))\n\t}\n\n\t// Decode the JSON body\n\tvar body ImageToImageResponse\n\tif err := json.NewDecoder(res.Body).Decode(&body); err != nil {\n\t\tpanic(err)\n\t}\n\n\t// Write the images to disk\n\tfor i, image := range body.Images {\n\t\toutFile := fmt.Sprintf(\"./out/v1_img2img_%d.png\", i)\n\t\tfile, err := os.Create(outFile)\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\timageBytes, err := base64.StdEncoding.DecodeString(image.Base64)\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tif _, err := file.Write(imageBytes); err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tif err := file.Close(); err != nil {\n\t\t\tpanic(err)\n\t\t}\n\t}\n}\n" }, { "lang": "cURL", "source": "if [ -z \"$STABILITY_API_KEY\" ]; then\n echo \"STABILITY_API_KEY environment variable is not set\"\n exit 1\nfi\n\nOUTPUT_FILE=./out/v1_img2img.png\nBASE_URL=${API_HOST:-https://api.stability.ai}\nURL=\"$BASE_URL/v1/generation/stable-diffusion-v1-6/image-to-image\"\n\ncurl -f -sS -X POST \"$URL\" \\\n -H 'Content-Type: multipart/form-data' \\\n -H 'Accept: image/png' \\\n -H \"Authorization: Bearer $STABILITY_API_KEY\" \\\n -F 'init_image=@\"../init_image.png\"' \\\n -F 'init_image_mode=IMAGE_STRENGTH' \\\n -F 'image_strength=0.35' \\\n -F 'text_prompts[0][text]=A galactic dog in space' \\\n -F 'cfg_scale=7' \\\n -F 'samples=1' \\\n -F 'steps=30' \\\n -o \"$OUTPUT_FILE\"\n" } ] } }, "/v1/generation/{engine_id}/image-to-image/masking": { "post": { "description": "Selectively modify portions of an image using a mask. The `mask` must be the same shape and size as the init image. This endpoint also supports `image` parameters with alpha channels. See below for more details. \n\n> NOTE: Only **Version 1** engines will work with this endpoint.", "operationId": "masking", "summary": "Image-to-image with a mask", "tags": [ "SDXL 1.0 & SD1.6" ], "parameters": [ { "example": "stable-diffusion-xl-1024-v1-0", "in": "path", "name": "engine_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/organization" }, { "$ref": "#/components/parameters/stabilityClientID" }, { "$ref": "#/components/parameters/stabilityClientVersion" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MaskingRequestBody" }, "examples": { "MASK_IMAGE_BLACK": { "value": { "mask_source": "MASK_IMAGE_BLACK", "init_image": "", "mask_image": "", "text_prompts[0][text]": "A dog space commander", "text_prompts[0][weight]": 1, "cfg_scale": 7, "sampler": "K_DPM_2_ANCESTRAL", "samples": 3, "steps": 30 } }, "MASK_IMAGE_WHITE": { "value": { "mask_source": "MASK_IMAGE_WHITE", "init_image": "", "mask_image": "", "text_prompts[0][text]": "A dog space commander", "text_prompts[0][weight]": 1, "cfg_scale": 7, "sampler": "K_DPM_2_ANCESTRAL", "samples": 3, "steps": 30 } }, "INIT_IMAGE_ALPHA": { "value": { "mask_source": "INIT_IMAGE_ALPHA", "init_image": "", "text_prompts[0][text]": "A dog space commander", "text_prompts[0][weight]": 1, "cfg_scale": 7, "sampler": "K_DPM_2_ANCESTRAL", "samples": 3, "steps": 30 } } } } } }, "responses": { "200": { "$ref": "#/components/responses/GenerationResponse" }, "400": { "$ref": "#/components/responses/400FromGeneration" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "STABILITY_API_KEY": [] } ], "x-codeSamples": [ { "lang": "Python", "source": "import base64\nimport os\nimport requests\n\nengine_id = \"stable-diffusion-v1-6\"\napi_host = os.getenv('API_HOST', 'https://api.stability.ai')\napi_key = os.getenv(\"STABILITY_API_KEY\")\n\nif api_key is None:\n raise Exception(\"Missing Stability API key.\")\n\nresponse = requests.post(\n f\"{api_host}/v1/generation/{engine_id}/image-to-image/masking\",\n headers={\n \"Accept\": 'application/json',\n \"Authorization\": f\"Bearer {api_key}\"\n },\n files={\n 'init_image': open(\"../init_image.png\", 'rb'),\n 'mask_image': open(\"../mask_image_black.png\", 'rb'),\n },\n data={\n \"mask_source\": \"MASK_IMAGE_BLACK\",\n \"text_prompts[0][text]\": \"A large spiral galaxy with a bright central bulge and a ring of stars around it\",\n \"cfg_scale\": 7,\n \"clip_guidance_preset\": \"FAST_BLUE\",\n \"samples\": 1,\n \"steps\": 30,\n }\n)\n\nif response.status_code != 200:\n raise Exception(\"Non-200 response: \" + str(response.text))\n\ndata = response.json()\n\nfor i, image in enumerate(data[\"artifacts\"]):\n with open(f\"./out/v1_img2img_masking_{i}.png\", \"wb\") as f:\n f.write(base64.b64decode(image[\"base64\"]))\n" }, { "label": "TypeScript", "lang": "Javascript", "source": "import fetch from 'node-fetch'\nimport FormData from 'form-data'\nimport fs from 'node:fs'\n\nconst engineId = 'stable-diffusion-v1-6'\nconst apiHost = process.env.API_HOST ?? 'https://api.stability.ai'\nconst apiKey = process.env.STABILITY_API_KEY\n\nif (!apiKey) throw new Error('Missing Stability API key.')\n\n// NOTE: This example is using a NodeJS FormData library. Browser\n// implementations should use their native FormData class. React Native\n// implementations should also use their native FormData class.\nconst formData = new FormData()\nformData.append('init_image', fs.readFileSync('../init_image.png'))\nformData.append('mask_image', fs.readFileSync('../mask_image_black.png'))\nformData.append('mask_source', 'MASK_IMAGE_BLACK')\nformData.append(\n 'text_prompts[0][text]',\n 'A large spiral galaxy with a bright central bulge and a ring of stars around it'\n)\nformData.append('cfg_scale', '7')\nformData.append('clip_guidance_preset', 'FAST_BLUE')\nformData.append('samples', 1)\nformData.append('steps', 30)\n\nconst response = await fetch(\n `${apiHost}/v1/generation/${engineId}/image-to-image/masking`,\n {\n method: 'POST',\n headers: {\n ...formData.getHeaders(),\n Accept: 'application/json',\n Authorization: `Bearer ${apiKey}`,\n },\n body: formData,\n }\n)\n\nif (!response.ok) {\n throw new Error(`Non-200 response: ${await response.text()}`)\n}\n\ninterface GenerationResponse {\n artifacts: Array<{\n base64: string\n seed: number\n finishReason: string\n }>\n}\n\nconst responseJSON = (await response.json()) as GenerationResponse\n\nresponseJSON.artifacts.forEach((image, index) => {\n fs.writeFileSync(\n `out/v1_img2img_masking_${index}.png`,\n Buffer.from(image.base64, 'base64')\n )\n})\n" }, { "lang": "Go", "source": "package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/base64\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io\"\n\t\"mime/multipart\"\n\t\"net/http\"\n\t\"os\"\n)\n\ntype MaskingImage struct {\n\tBase64 string `json:\"base64\"`\n\tSeed uint32 `json:\"seed\"`\n\tFinishReason string `json:\"finishReason\"`\n}\n\ntype MaskingResponse struct {\n\tImages []MaskingImage `json:\"artifacts\"`\n}\n\nfunc main() {\n\tengineId := \"stable-diffusion-v1-6\"\n\n\t// Build REST endpoint URL\n\tapiHost, hasApiHost := os.LookupEnv(\"API_HOST\")\n\tif !hasApiHost {\n\t\tapiHost = \"https://api.stability.ai\"\n\t}\n\treqUrl := apiHost + \"/v1/generation/\" + engineId + \"/image-to-image/masking\"\n\n\t// Acquire an API key from the environment\n\tapiKey, hasAPIKey := os.LookupEnv(\"STABILITY_API_KEY\")\n\tif !hasAPIKey {\n\t\tpanic(\"Missing STABILITY_API_KEY environment variable\")\n\t}\n\n\tdata := &bytes.Buffer{}\n\twriter := multipart.NewWriter(data)\n\n\t// Write the init image to the request\n\tinitImageWriter, _ := writer.CreateFormField(\"init_image\")\n\tinitImageFile, initImageErr := os.Open(\"../init_image.png\")\n\tif initImageErr != nil {\n\t\tpanic(\"Could not open init_image.png\")\n\t}\n\t_, _ = io.Copy(initImageWriter, initImageFile)\n\n\t// Write the mask image to the request\n\tmaskImageWriter, _ := writer.CreateFormField(\"mask_image\")\n\tmaskImageFile, maskImageErr := os.Open(\"../mask_image_black.png\")\n\tif maskImageErr != nil {\n\t\tpanic(\"Could not open mask_image_white.png\")\n\t}\n\t_, _ = io.Copy(maskImageWriter, maskImageFile)\n\n\t// Write the options to the request\n\t_ = writer.WriteField(\"mask_source\", \"MASK_IMAGE_BLACK\")\n\t_ = writer.WriteField(\"text_prompts[0][text]\", \"A large spiral galaxy with a bright central bulge and a ring of stars around it\")\n\t_ = writer.WriteField(\"cfg_scale\", \"7\")\n\t_ = writer.WriteField(\"clip_guidance_preset\", \"FAST_BLUE\")\n\t_ = writer.WriteField(\"samples\", \"1\")\n\t_ = writer.WriteField(\"steps\", \"30\")\n\twriter.Close()\n\n\t// Execute the request & read all the bytes of the response\n\tpayload := bytes.NewReader(data.Bytes())\n\treq, _ := http.NewRequest(\"POST\", reqUrl, payload)\n\treq.Header.Add(\"Content-Type\", writer.FormDataContentType())\n\treq.Header.Add(\"Accept\", \"application/json\")\n\treq.Header.Add(\"Authorization\", \"Bearer \"+apiKey)\n\tres, _ := http.DefaultClient.Do(req)\n\tdefer res.Body.Close()\n\n\tif res.StatusCode != 200 {\n\t\tvar body map[string]interface{}\n\t\tif err := json.NewDecoder(res.Body).Decode(&body); err != nil {\n\t\t\tpanic(err)\n\t\t}\n\t\tpanic(fmt.Sprintf(\"Non-200 response: %s\", body))\n\t}\n\n\t// Decode the JSON body\n\tvar body MaskingResponse\n\tif err := json.NewDecoder(res.Body).Decode(&body); err != nil {\n\t\tpanic(err)\n\t}\n\n\t// Write the images to disk\n\tfor i, image := range body.Images {\n\t\toutFile := fmt.Sprintf(\"./out/v1_img2img_masking_%d.png\", i)\n\t\tfile, err := os.Create(outFile)\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\timageBytes, err := base64.StdEncoding.DecodeString(image.Base64)\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tif _, err := file.Write(imageBytes); err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tif err := file.Close(); err != nil {\n\t\t\tpanic(err)\n\t\t}\n\t}\n}\n" }, { "lang": "cURL", "source": "#!/bin/sh\n\nset -e\n\nif [ -z \"$STABILITY_API_KEY\" ]; then\n echo \"STABILITY_API_KEY environment variable is not set\"\n exit 1\nfi\n\nOUTPUT_FILE=./out/v1_img2img_masking.png\nBASE_URL=${API_HOST:-https://api.stability.ai}\nURL=\"$BASE_URL/v1/generation/stable-diffusion-v1-6/image-to-image/masking\"\n\ncurl -f -sS -X POST \"$URL\" \\\n -H 'Content-Type: multipart/form-data' \\\n -H 'Accept: image/png' \\\n -H \"Authorization: Bearer $STABILITY_API_KEY\" \\\n -F 'init_image=@\"../init_image.png\"' \\\n -F 'mask_image=@\"../mask_image_black.png\"' \\\n -F 'mask_source=MASK_IMAGE_BLACK' \\\n -F 'text_prompts[0][text]=A large spiral galaxy with a bright central bulge and a ring of stars around it' \\\n -F 'cfg_scale=7' \\\n -F 'clip_guidance_preset=FAST_BLUE' \\\n -F 'samples=1' \\\n -F 'steps=30' \\\n -o \"$OUTPUT_FILE\"\n" } ] } }, "/v1/engines/list": { "get": { "description": "List all engines available to your organization/user", "operationId": "listEngines", "summary": "List engines", "tags": [ "Engines" ], "parameters": [ { "$ref": "#/components/parameters/organization" }, { "$ref": "#/components/parameters/stabilityClientID" }, { "$ref": "#/components/parameters/stabilityClientVersion" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnginesResponseBody" } } }, "description": "OK response." }, "401": { "$ref": "#/components/responses/401" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "STABILITY_API_KEY": [] } ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\napi_host = os.getenv('API_HOST', 'https://api.stability.ai')\nurl = f\"{api_host}/v1/engines/list\"\n\napi_key = os.getenv(\"STABILITY_API_KEY\")\nif api_key is None:\n raise Exception(\"Missing Stability API key.\")\n\nresponse = requests.get(url, headers={\n \"Authorization\": f\"Bearer {api_key}\"\n})\n\nif response.status_code != 200:\n raise Exception(\"Non-200 response: \" + str(response.text))\n\n# Do something with the payload...\npayload = response.json()\n\n" }, { "label": "TypeScript", "lang": "Javascript", "source": "import fetch from 'node-fetch'\n\nconst apiHost = process.env.API_HOST ?? 'https://api.stability.ai'\nconst url = `${apiHost}/v1/engines/list`\n\nconst apiKey = process.env.STABILITY_API_KEY\nif (!apiKey) throw new Error('Missing Stability API key.')\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${apiKey}`,\n },\n})\n\nif (!response.ok) {\n throw new Error(`Non-200 response: ${await response.text()}`)\n}\n\ninterface Payload {\n engines: Array<{\n id: string\n name: string\n description: string\n type: string\n }>\n}\n\n// Do something with the payload...\nconst payload = (await response.json()) as Payload\n" }, { "lang": "Go", "source": "package main\n\nimport (\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\t// Build REST endpoint URL\n\tapiHost, hasApiHost := os.LookupEnv(\"API_HOST\")\n\tif !hasApiHost {\n\t\tapiHost = \"https://api.stability.ai\"\n\t}\n\treqUrl := apiHost + \"/v1/engines/list\"\n\n\t// Acquire an API key from the environment\n\tapiKey, hasAPIKey := os.LookupEnv(\"STABILITY_API_KEY\")\n\tif !hasAPIKey {\n\t\tpanic(\"Missing STABILITY_API_KEY environment variable\")\n\t}\n\n\t// Execute the request & read all the bytes of the response\n\treq, _ := http.NewRequest(\"GET\", reqUrl, nil)\n\treq.Header.Add(\"Authorization\", \"Bearer \"+apiKey)\n\tres, _ := http.DefaultClient.Do(req)\n\tdefer res.Body.Close()\n\tbody, _ := io.ReadAll(res.Body)\n\n\tif res.StatusCode != 200 {\n\t\tpanic(\"Non-200 response: \" + string(body))\n\t}\n\n\t// Do something with the payload...\n\t// payload := string(body)\n}\n" }, { "lang": "cURL", "source": "if [ -z \"$STABILITY_API_KEY\" ]; then\n echo \"STABILITY_API_KEY environment variable is not set\"\n exit 1\nfi\n\nBASE_URL=${API_HOST:-https://api.stability.ai}\nURL=\"$BASE_URL/v1/engines/list\"\n\ncurl -f -sS \"$URL\" \\\n -H 'Accept: application/json' \\\n -H \"Authorization: Bearer $STABILITY_API_KEY\"\n" } ] } }, "/v1/user/account": { "get": { "description": "Get information about the account associated with the provided API key", "operationId": "userAccount", "summary": "Account details", "tags": [ "User" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseBody" } } }, "description": "OK response." }, "401": { "$ref": "#/components/responses/401" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "STABILITY_API_KEY": [] } ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\napi_host = os.getenv('API_HOST', 'https://api.stability.ai')\nurl = f\"{api_host}/v1/user/account\"\n\napi_key = os.getenv(\"STABILITY_API_KEY\")\nif api_key is None:\n raise Exception(\"Missing Stability API key.\")\n\nresponse = requests.get(url, headers={\n \"Authorization\": f\"Bearer {api_key}\"\n})\n\nif response.status_code != 200:\n raise Exception(\"Non-200 response: \" + str(response.text))\n\n# Do something with the payload...\npayload = response.json()\n\n" }, { "label": "TypeScript", "lang": "Javascript", "source": "import fetch from 'node-fetch'\n\nconst apiHost = process.env.API_HOST ?? 'https://api.stability.ai'\nconst url = `${apiHost}/v1/user/account`\n\nconst apiKey = process.env.STABILITY_API_KEY\nif (!apiKey) throw new Error('Missing Stability API key.')\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${apiKey}`,\n },\n})\n\nif (!response.ok) {\n throw new Error(`Non-200 response: ${await response.text()}`)\n}\n\ninterface User {\n id: string\n profile_picture: string\n email: string\n organizations?: Array<{\n id: string\n name: string\n role: string\n is_default: boolean\n }>\n}\n\n// Do something with the user...\nconst user = (await response.json()) as User\n" }, { "lang": "Go", "source": "package main\n\nimport (\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\t// Build REST endpoint URL\n\tapiHost, hasApiHost := os.LookupEnv(\"API_HOST\")\n\tif !hasApiHost {\n\t\tapiHost = \"https://api.stability.ai\"\n\t}\n\treqUrl := apiHost + \"/v1/user/account\"\n\n\t// Acquire an API key from the environment\n\tapiKey, hasAPIKey := os.LookupEnv(\"STABILITY_API_KEY\")\n\tif !hasAPIKey {\n\t\tpanic(\"Missing STABILITY_API_KEY environment variable\")\n\t}\n\n\t// Build the request\n\treq, _ := http.NewRequest(\"GET\", reqUrl, nil)\n\treq.Header.Add(\"Authorization\", \"Bearer \"+apiKey)\n\n\t// Execute the request\n\tres, _ := http.DefaultClient.Do(req)\n\tdefer res.Body.Close()\n\tbody, _ := io.ReadAll(res.Body)\n\n\tif res.StatusCode != 200 {\n\t\tpanic(\"Non-200 response: \" + string(body))\n\t}\n\n\t// Do something with the payload...\n\t// payload := string(body)\n}\n" }, { "lang": "cURL", "source": "if [ -z \"$STABILITY_API_KEY\" ]; then\n echo \"STABILITY_API_KEY environment variable is not set\"\n exit 1\nfi\n\n# Determine the URL to use for the request\nBASE_URL=${API_HOST:-https://api.stability.ai}\nURL=\"$BASE_URL/v1/user/account\"\n\ncurl -f -sS \"$URL\" \\\n -H 'Accept: application/json' \\\n -H \"Authorization: Bearer $STABILITY_API_KEY\"\n" } ] } }, "/v1/user/balance": { "get": { "description": "Get the credit balance of the account/organization associated with the API key", "operationId": "userBalance", "summary": "Account balance", "tags": [ "User" ], "parameters": [ { "$ref": "#/components/parameters/organization" }, { "$ref": "#/components/parameters/stabilityClientID" }, { "$ref": "#/components/parameters/stabilityClientVersion" } ], "responses": { "200": { "content": { "application/json": { "example": { "credits": 0.6336833840314097 }, "schema": { "$ref": "#/components/schemas/BalanceResponseBody" } } }, "description": "OK response." }, "401": { "$ref": "#/components/responses/401" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "STABILITY_API_KEY": [] } ], "x-codeSamples": [ { "lang": "Python", "source": "import os\nimport requests\n\napi_host = os.getenv('API_HOST', 'https://api.stability.ai')\nurl = f\"{api_host}/v1/user/balance\"\n\napi_key = os.getenv(\"STABILITY_API_KEY\")\nif api_key is None:\n raise Exception(\"Missing Stability API key.\")\n\nresponse = requests.get(url, headers={\n \"Authorization\": f\"Bearer {api_key}\"\n})\n\nif response.status_code != 200:\n raise Exception(\"Non-200 response: \" + str(response.text))\n\n# Do something with the payload...\npayload = response.json()\n\n" }, { "label": "TypeScript", "lang": "Javascript", "source": "import fetch from 'node-fetch'\n\nconst apiHost = process.env.API_HOST ?? 'https://api.stability.ai'\nconst url = `${apiHost}/v1/user/balance`\n\nconst apiKey = process.env.STABILITY_API_KEY\nif (!apiKey) throw new Error('Missing Stability API key.')\n\nconst response = await fetch(url, {\n method: 'GET',\n headers: {\n Authorization: `Bearer ${apiKey}`,\n },\n})\n\nif (!response.ok) {\n throw new Error(`Non-200 response: ${await response.text()}`)\n}\n\ninterface Balance {\n credits: number\n}\n\n// Do something with the balance...\nconst balance = (await response.json()) as Balance\n" }, { "lang": "Go", "source": "package main\n\nimport (\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\t// Build REST endpoint URL\n\tapiHost, hasApiHost := os.LookupEnv(\"API_HOST\")\n\tif !hasApiHost {\n\t\tapiHost = \"https://api.stability.ai\"\n\t}\n\treqUrl := apiHost + \"/v1/user/balance\"\n\n\t// Acquire an API key from the environment\n\tapiKey, hasAPIKey := os.LookupEnv(\"STABILITY_API_KEY\")\n\tif !hasAPIKey {\n\t\tpanic(\"Missing STABILITY_API_KEY environment variable\")\n\t}\n\n\t// Build the request\n\treq, _ := http.NewRequest(\"GET\", reqUrl, nil)\n\treq.Header.Add(\"Authorization\", \"Bearer \"+apiKey)\n\n\t// Execute the request\n\tres, _ := http.DefaultClient.Do(req)\n\tdefer res.Body.Close()\n\tbody, _ := io.ReadAll(res.Body)\n\n\tif res.StatusCode != 200 {\n\t\tpanic(\"Non-200 response: \" + string(body))\n\t}\n\n\t// Do something with the payload...\n\t// payload := string(body)\n}\n" }, { "lang": "cURL", "source": "if [ -z \"$STABILITY_API_KEY\" ]; then\n echo \"STABILITY_API_KEY environment variable is not set\"\n exit 1\nfi\n\n# Determine the URL to use for the request\nBASE_URL=${API_HOST:-https://api.stability.ai}\nURL=\"$BASE_URL/v1/user/balance\"\n\ncurl -f -sS \"$URL\" \\\n -H 'Content-Type: application/json' \\\n -H \"Authorization: Bearer $STABILITY_API_KEY\"\n" } ] } } }, "components": { "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" }, "ImageToVideoRequest": { "type": "object", "properties": { "image": { "type": "string", "description": "The source image used in the video generation process.\n\nSupported Formats:\n- jpeg\n- png\n\nSupported Dimensions:\n- 1024x576\n- 576x1024\n- 768x768", "format": "binary", "example": "./some/image.png" }, "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.)" }, "cfg_scale": { "type": "number", "minimum": 0, "maximum": 10, "default": 1.8, "description": "How strongly the video sticks to the original image. Use lower values to allow the model more freedom to make changes and higher values to correct motion distortions." }, "motion_bucket_id": { "type": "number", "minimum": 1, "maximum": 255, "default": 127, "description": "Lower values generally result in less motion in the output video, while higher values generally result in more motion. This parameter corresponds to the motion_bucket_id parameter from the [paper](https://static1.squarespace.com/static/6213c340453c3f502425776e/t/655ce779b9d47d342a93c890/1700587395994/stable_video_diffusion.pdf)." } }, "required": [ "image" ] }, "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://stabilityplatform.freshdesk.com/support/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://stabilityplatform.freshdesk.com/support/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." }, "Engine": { "type": "object", "properties": { "description": { "type": "string" }, "id": { "type": "string", "x-go-name": "ID", "description": "Unique identifier for the engine", "example": "stable-diffusion-v1-6" }, "name": { "type": "string", "description": "Name of the engine", "example": "Stable Diffusion XL v1.0" }, "type": { "type": "string", "description": "The type of content this engine produces", "example": "PICTURE", "enum": [ "AUDIO", "CLASSIFICATION", "PICTURE", "STORAGE", "TEXT", "VIDEO" ] } }, "required": [ "id", "name", "description", "type" ] }, "Error": { "type": "object", "x-go-name": "RESTError", "properties": { "id": { "x-go-name": "ID", "type": "string", "description": "A unique identifier for this particular occurrence of the problem.", "example": "296a972f-666a-44a1-a3df-c9c28a1f56c0" }, "name": { "type": "string", "description": "The short-name of this class of errors e.g. `bad_request`.", "example": "bad_request" }, "message": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem.", "example": "Header parameter Authorization is required, but not found" } }, "required": [ "name", "id", "message", "status" ] }, "CfgScale": { "type": "number", "description": "How strictly the diffusion process adheres to the prompt text (higher values keep your image closer to your prompt)", "default": 7, "example": 7, "minimum": 0, "maximum": 35 }, "ClipGuidancePreset": { "type": "string", "default": "NONE", "example": "FAST_BLUE", "enum": [ "FAST_BLUE", "FAST_GREEN", "NONE", "SIMPLE", "SLOW", "SLOWER", "SLOWEST" ] }, "UpscaleImageHeight": { "x-go-type": "uint64", "type": "integer", "description": "Desired height of the output image. Only one of `width` or `height` may be specified.", "minimum": 512 }, "UpscaleImageWidth": { "x-go-type": "uint64", "type": "integer", "description": "Desired width of the output image. Only one of `width` or `height` may be specified.", "minimum": 512 }, "DiffuseImageHeight": { "x-go-type": "uint64", "type": "integer", "description": "Height of the image to generate, in pixels, in an increment divisible by 64.", "multipleOf": 64, "default": 512, "example": 512, "minimum": 128 }, "DiffuseImageWidth": { "x-go-type": "uint64", "type": "integer", "description": "Width of the image to generate, in pixels, in an increment divisible by 64.", "multipleOf": 64, "default": 512, "example": 512, "minimum": 128 }, "Sampler": { "type": "string", "description": "Which sampler to use for the diffusion process. If this value is omitted we'll automatically select an appropriate sampler for you.", "example": "K_DPM_2_ANCESTRAL", "enum": [ "DDIM", "DDPM", "K_DPMPP_2M", "K_DPMPP_2S_ANCESTRAL", "K_DPM_2", "K_DPM_2_ANCESTRAL", "K_EULER", "K_EULER_ANCESTRAL", "K_HEUN", "K_LMS" ] }, "Samples": { "x-go-type": "uint64", "type": "integer", "description": "Number of images to generate", "default": 1, "example": 1, "minimum": 1, "maximum": 10 }, "Seed": { "type": "integer", "x-go-type": "uint32", "description": "Random noise seed (omit this option or use `0` for a random seed)", "default": 0, "example": 0, "minimum": 0, "maximum": 4294967295 }, "Steps": { "x-go-type": "uint64", "type": "integer", "description": "Number of diffusion steps to run.", "default": 30, "example": 50, "minimum": 10, "maximum": 50 }, "Extras": { "type": "object", "description": "Extra parameters passed to the engine.\nThese parameters are used for in-development or experimental features and may change\nwithout warning, so please use with caution." }, "StylePreset": { "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": "Pass in a style preset to guide the image model towards a particular style.\nThis list of style presets is subject to change." }, "TextPrompt": { "type": "object", "properties": { "text": { "type": "string", "description": "The prompt itself", "example": "A lighthouse on a cliff", "maxLength": 2000 }, "weight": { "type": "number", "description": "Weight of the prompt (use negative numbers for negative prompts)", "example": 0.8167237, "format": "float" } }, "description": "Text prompt for image generation", "required": [ "text" ] }, "TextPromptsForTextToImage": { "title": "TextPrompts", "type": "array", "items": { "$ref": "#/components/schemas/TextPrompt" }, "minItems": 1, "description": "An array of text prompts to use for generation.\n\nGiven a text prompt with the text `A lighthouse on a cliff` and a weight of `0.5`, it would be represented as:\n\n```\n\"text_prompts\": [\n {\n \"text\": \"A lighthouse on a cliff\",\n \"weight\": 0.5\n }\n]\n```" }, "TextPrompts": { "description": "An array of text prompts to use for generation.\n\nDue to how arrays are represented in `multipart/form-data` requests, prompts must adhere to the format `text_prompts[index][text|weight]`,\nwhere `index` is some integer used to tie the text and weight together. While `index` does not have to be sequential, duplicate entries \nwill override previous entries, so it is recommended to use sequential indices.\n\nGiven a text prompt with the text `A lighthouse on a cliff` and a weight of `0.5`, it would be represented as:\n```\ntext_prompts[0][text]: \"A lighthouse on a cliff\"\ntext_prompts[0][weight]: 0.5\n```\n\nTo add another prompt to that request simply provide the values under a new `index`:\n\n```\ntext_prompts[0][text]: \"A lighthouse on a cliff\"\ntext_prompts[0][weight]: 0.5\ntext_prompts[1][text]: \"land, ground, dirt, grass\"\ntext_prompts[1][weight]: -0.9\n```", "type": "array", "items": { "$ref": "#/components/schemas/TextPrompt" }, "minItems": 1 }, "InputImage": { "x-go-type": "[]byte", "type": "string", "description": "The image to upscale using ESRGAN.", "example": "", "format": "binary" }, "InitImage": { "x-go-type": "[]byte", "type": "string", "description": "Image used to initialize the diffusion process, in lieu of random noise.", "example": "", "format": "binary" }, "InitImageStrength": { "type": "number", "description": "How much influence the `init_image` has on the diffusion process. Values close to `1` will yield images very similar to the `init_image` while values close to `0` will yield images wildly different than the `init_image`. The behavior of this is meant to mirror DreamStudio's \"Image Strength\" slider.

This parameter is just an alternate way to set `step_schedule_start`, which is done via the calculation `1 - image_strength`. For example, passing in an Image Strength of 35% (`0.35`) would result in a `step_schedule_start` of `0.65`.\n", "example": 0.4, "minimum": 0, "maximum": 1, "format": "float", "default": 0.35 }, "InitImageMode": { "type": "string", "description": "Whether to use `image_strength` or `step_schedule_*` to control how much influence the `init_image` has on the result.", "enum": [ "IMAGE_STRENGTH", "STEP_SCHEDULE" ], "default": "IMAGE_STRENGTH" }, "StepScheduleStart": { "type": "number", "description": "Skips a proportion of the start of the diffusion steps, allowing the init_image to influence the final generated image. Lower values will result in more influence from the init_image, while higher values will result in more influence from the diffusion steps. (e.g. a value of `0` would simply return you the init_image, where a value of `1` would return you a completely different image.)", "default": 0.65, "example": 0.4, "minimum": 0, "maximum": 1 }, "StepScheduleEnd": { "type": "number", "description": "Skips a proportion of the end of the diffusion steps, allowing the init_image to influence the final generated image. Lower values will result in more influence from the init_image, while higher values will result in more influence from the diffusion steps.", "example": 0.01, "minimum": 0, "maximum": 1 }, "MaskImage": { "x-go-type": "[]byte", "type": "string", "description": "Optional grayscale mask that allows for influence over which pixels are eligible for diffusion and at what strength. Must be the same dimensions as the `init_image`. Use the `mask_source` option to specify whether the white or black pixels should be inpainted.", "example": "", "format": "binary" }, "MaskSource": { "type": "string", "description": "For any given pixel, the mask determines the strength of generation on a linear scale. This parameter determines where to source the mask from:\n- `MASK_IMAGE_WHITE` will use the white pixels of the mask_image as the mask, where white pixels are completely replaced and black pixels are unchanged\n- `MASK_IMAGE_BLACK` will use the black pixels of the mask_image as the mask, where black pixels are completely replaced and white pixels are unchanged\n- `INIT_IMAGE_ALPHA` will use the alpha channel of the init_image as the mask, where fully transparent pixels are completely replaced and fully opaque pixels are unchanged" }, "GenerationRequestOptionalParams": { "type": "object", "description": "Represents the optional parameters that can be passed to any generation request.", "properties": { "cfg_scale": { "$ref": "#/components/schemas/CfgScale" }, "clip_guidance_preset": { "$ref": "#/components/schemas/ClipGuidancePreset" }, "sampler": { "$ref": "#/components/schemas/Sampler" }, "samples": { "$ref": "#/components/schemas/Samples" }, "seed": { "$ref": "#/components/schemas/Seed" }, "steps": { "$ref": "#/components/schemas/Steps" }, "style_preset": { "$ref": "#/components/schemas/StylePreset" }, "extras": { "$ref": "#/components/schemas/Extras" } } }, "RealESRGANUpscaleRequestBody": { "type": "object", "properties": { "image": { "$ref": "#/components/schemas/InputImage" }, "width": { "$ref": "#/components/schemas/UpscaleImageWidth" }, "height": { "$ref": "#/components/schemas/UpscaleImageHeight" } }, "required": [ "image" ] }, "ImageToImageRequestBody": { "type": "object", "properties": { "text_prompts": { "$ref": "#/components/schemas/TextPrompts" }, "init_image": { "$ref": "#/components/schemas/InitImage" }, "init_image_mode": { "$ref": "#/components/schemas/InitImageMode" }, "image_strength": { "$ref": "#/components/schemas/InitImageStrength" }, "step_schedule_start": { "$ref": "#/components/schemas/StepScheduleStart" }, "step_schedule_end": { "$ref": "#/components/schemas/StepScheduleEnd" }, "cfg_scale": { "$ref": "#/components/schemas/CfgScale" }, "clip_guidance_preset": { "$ref": "#/components/schemas/ClipGuidancePreset" }, "sampler": { "$ref": "#/components/schemas/Sampler" }, "samples": { "$ref": "#/components/schemas/Samples" }, "seed": { "$ref": "#/components/schemas/Seed" }, "steps": { "$ref": "#/components/schemas/Steps" }, "style_preset": { "$ref": "#/components/schemas/StylePreset" }, "extras": { "$ref": "#/components/schemas/Extras" } }, "required": [ "text_prompts", "init_image" ], "discriminator": { "propertyName": "init_image_mode", "mapping": { "IMAGE_STRENGTH": "#/components/schemas/ImageToImageUsingImageStrengthRequestBody", "STEP_SCHEDULE": "#/components/schemas/ImageToImageUsingStepScheduleRequestBody" } } }, "ImageToImageUsingImageStrengthRequestBody": { "allOf": [ { "type": "object", "properties": { "text_prompts": { "$ref": "#/components/schemas/TextPrompts" }, "init_image": { "$ref": "#/components/schemas/InitImage" }, "init_image_mode": { "$ref": "#/components/schemas/InitImageMode" }, "image_strength": { "$ref": "#/components/schemas/InitImageStrength" } }, "required": [ "text_prompts", "init_image" ] }, { "$ref": "#/components/schemas/GenerationRequestOptionalParams" } ] }, "ImageToImageUsingStepScheduleRequestBody": { "allOf": [ { "type": "object", "properties": { "text_prompts": { "$ref": "#/components/schemas/TextPrompts" }, "init_image": { "$ref": "#/components/schemas/InitImage" }, "init_image_mode": { "$ref": "#/components/schemas/InitImageMode" }, "step_schedule_start": { "$ref": "#/components/schemas/StepScheduleStart" }, "step_schedule_end": { "$ref": "#/components/schemas/StepScheduleEnd" } }, "required": [ "text_prompts", "init_image" ] }, { "$ref": "#/components/schemas/GenerationRequestOptionalParams" } ] }, "MaskingRequestBody": { "type": "object", "properties": { "init_image": { "$ref": "#/components/schemas/InitImage" }, "mask_source": { "$ref": "#/components/schemas/MaskSource" }, "mask_image": { "$ref": "#/components/schemas/MaskImage" }, "text_prompts": { "$ref": "#/components/schemas/TextPrompts" }, "cfg_scale": { "$ref": "#/components/schemas/CfgScale" }, "clip_guidance_preset": { "$ref": "#/components/schemas/ClipGuidancePreset" }, "sampler": { "$ref": "#/components/schemas/Sampler" }, "samples": { "$ref": "#/components/schemas/Samples" }, "seed": { "$ref": "#/components/schemas/Seed" }, "steps": { "$ref": "#/components/schemas/Steps" }, "style_preset": { "$ref": "#/components/schemas/StylePreset" }, "extras": { "$ref": "#/components/schemas/Extras" } }, "required": [ "text_prompts", "init_image", "mask_source" ], "discriminator": { "propertyName": "mask_source", "mapping": { "MASK_IMAGE_BLACK": "#/components/schemas/MaskingUsingMaskImageRequestBody", "MASK_IMAGE_WHITE": "#/components/schemas/MaskingUsingMaskImageRequestBody", "INIT_IMAGE_ALPHA": "#/components/schemas/MaskingUsingInitImageAlphaRequestBody" } } }, "MaskingUsingMaskImageRequestBody": { "allOf": [ { "type": "object", "properties": { "text_prompts": { "$ref": "#/components/schemas/TextPrompts" }, "init_image": { "$ref": "#/components/schemas/InitImage" }, "mask_source": { "$ref": "#/components/schemas/MaskSource" }, "mask_image": { "$ref": "#/components/schemas/MaskImage" } }, "required": [ "init_image", "mask_image", "text_prompts", "mask_source" ] }, { "$ref": "#/components/schemas/GenerationRequestOptionalParams" } ] }, "MaskingUsingInitImageAlphaRequestBody": { "allOf": [ { "type": "object", "properties": { "text_prompts": { "$ref": "#/components/schemas/TextPrompts" }, "init_image": { "$ref": "#/components/schemas/InitImage" }, "mask_source": { "$ref": "#/components/schemas/MaskSource" } }, "required": [ "init_image", "text_prompts", "mask_source" ] }, { "$ref": "#/components/schemas/GenerationRequestOptionalParams" } ] }, "TextToImageRequestBody": { "type": "object", "allOf": [ { "type": "object", "properties": { "height": { "$ref": "#/components/schemas/DiffuseImageHeight" }, "width": { "$ref": "#/components/schemas/DiffuseImageWidth" }, "text_prompts": { "$ref": "#/components/schemas/TextPromptsForTextToImage" } }, "required": [ "text_prompts" ] }, { "$ref": "#/components/schemas/GenerationRequestOptionalParams" } ], "example": { "cfg_scale": 7, "height": 512, "width": 512, "sampler": "K_DPM_2_ANCESTRAL", "samples": 1, "seed": 0, "steps": 30, "text_prompts": [ { "text": "A lighthouse on a cliff", "weight": 1 } ] }, "required": [ "text_prompts" ] }, "AccountResponseBody": { "type": "object", "properties": { "email": { "type": "string", "description": "The user's email", "example": "example@stability.ai", "format": "email" }, "id": { "type": "string", "description": "The user's ID", "example": "user-1234", "x-go-name": "ID" }, "organizations": { "type": "array", "example": [ { "id": "org-5678", "name": "Another Organization", "role": "MEMBER", "is_default": true }, { "id": "org-1234", "name": "My Organization", "role": "MEMBER", "is_default": false } ], "items": { "$ref": "#/components/schemas/OrganizationMembership" }, "description": "The user's organizations" }, "profile_picture": { "type": "string", "description": "The user's profile picture", "example": "https://api.stability.ai/example.png", "format": "uri" } }, "required": [ "id", "email", "organizations" ] }, "BalanceResponseBody": { "type": "object", "properties": { "credits": { "type": "number", "description": "The balance of the account/organization associated with the API key", "example": 0.41122252265928866, "format": "double" } }, "example": { "credits": 0.07903292496944721 }, "required": [ "credits" ] }, "ListEnginesResponseBody": { "type": "array", "description": "The engines available to your user/organization", "items": { "$ref": "#/components/schemas/Engine" }, "example": [ { "description": "Stability-AI Stable Diffusion v1.6", "id": "stable-diffusion-v1-6", "name": "Stable Diffusion v1.6", "type": "PICTURE" }, { "description": "Stability-AI Stable Diffusion XL v1.0", "id": "stable-diffusion-xl-1024-v1-0", "name": "Stable Diffusion XL v1.0", "type": "PICTURE" } ] }, "FinishReason": { "type": "string", "description": "The result of the generation process.\n- `SUCCESS` indicates success\n- `ERROR` indicates an error\n- `CONTENT_FILTERED` indicates the result affected by the content filter and may be blurred.\n\nThis header is only present when the `Accept` is set to `image/png`. Otherwise it is returned in the response body.", "enum": [ "SUCCESS", "ERROR", "CONTENT_FILTERED" ] }, "Image": { "type": "object", "properties": { "base64": { "type": "string", "x-go-type-skip-optional-pointer": true, "description": "Image encoded in base64" }, "finishReason": { "type": "string", "x-go-type-skip-optional-pointer": true, "example": "CONTENT_FILTERED", "enum": [ "SUCCESS", "ERROR", "CONTENT_FILTERED" ] }, "seed": { "type": "number", "x-go-type-skip-optional-pointer": true, "description": "The seed associated with this image", "example": 1229191277 } }, "example": [ { "base64": "...very long string...", "finishReason": "SUCCESS", "seed": 1050625087 }, { "base64": "...very long string...", "finishReason": "CONTENT_FILTERED", "seed": 1229191277 } ] }, "OrganizationMembership": { "type": "object", "properties": { "id": { "type": "string", "example": "org-123456", "x-go-name": "ID" }, "is_default": { "type": "boolean", "example": false }, "name": { "type": "string", "example": "My Organization" }, "role": { "type": "string", "example": "MEMBER" } }, "required": [ "id", "name", "role", "is_default" ] } }, "parameters": { "upscaleEngineID": { "in": "path", "name": "engine_id", "required": true, "schema": { "type": "string" }, "examples": { "ESRGAN_X2_PLUS": { "description": "ESRGAN x2 Upscaler", "value": "esrgan-v1-x2plus" } } }, "engineID": { "examples": { "default": { "value": "stable-diffusion-v1-6", "description": "Stable Diffusion v1.6" }, "stable-diffusion-xl-1024-v1-0": { "value": "stable-diffusion-xl-1024-v1-0", "description": "Stable Diffusion XL v1.0" } }, "in": "path", "name": "engine_id", "required": true, "schema": { "type": "string" } }, "organization": { "allowEmptyValue": false, "description": "Allows for requests to be scoped to an organization other than the user's default. If not provided, the user's default organization will be used.", "example": "org-123456", "in": "header", "name": "Organization", "x-go-name": "OrganizationID", "schema": { "type": "string" } }, "stabilityClientID": { "allowEmptyValue": false, "description": "Used to identify the source of requests, such as the client application or sub-organization. Optional, but recommended for organizational clarity.", "example": "my-great-plugin", "in": "header", "name": "Stability-Client-ID", "schema": { "type": "string" } }, "stabilityClientVersion": { "allowEmptyValue": false, "description": "Used to identify the version of the application or service making the requests. Optional, but recommended for organizational clarity.", "example": "1.2.1", "in": "header", "name": "Stability-Client-Version", "schema": { "type": "string" } }, "accept": { "allowEmptyValue": false, "in": "header", "name": "Accept", "description": "The format of the response. Leave blank for JSON, or set to 'image/png' for a PNG image.", "schema": { "default": "application/json", "enum": [ "application/json", "image/png" ], "type": "string" } } }, "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." } }, "responses": { "401": { "description": "unauthorized: API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "9160aa70-222f-4a36-9eb7-475e2668362a", "name": "unauthorized", "message": "missing authorization header" } } } }, "403": { "description": "permission_denied: You lack the necessary permissions to perform this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "5cf19777-d17f-49fe-9bd9-39ff0ec6bb50", "name": "permission_denied", "message": "You do not have permission to access this resource" } } } }, "404": { "description": "not_found: The requested resource/engine was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "92b19e7f-22a2-4e71-a821-90edda229293", "name": "not_found", "message": "The specified engine (ID some-fake-engine) was not found." } } } }, "500": { "description": "server_error: Some unexpected server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "f81964d6-619b-453e-97bc-9fd7ac3f04e7", "name": "server_error", "message": "An unexpected server error occurred, please try again." } } } }, "GenerationResponse": { "description": "Generation successful.", "content": { "application/json": { "schema": { "description": "An array of results from the generation request, where each image is a base64 encoded PNG.", "type": "object", "properties": { "artifacts": { "type": "array", "x-go-type-skip-optional-pointer": true, "items": { "$ref": "#/components/schemas/Image" } } } } }, "image/png": { "example": "The bytes of the generated image, what did you expect?", "schema": { "description": "The bytes of the generated PNG image", "format": "binary", "type": "string" } } }, "headers": { "Content-Length": { "$ref": "#/components/headers/Content-Length" }, "Content-Type": { "$ref": "#/components/headers/Content-Type" }, "Finish-Reason": { "$ref": "#/components/headers/Finish-Reason" }, "Seed": { "$ref": "#/components/headers/Seed" } } }, "400FromGeneration": { "description": "bad_request: one or more parameters were invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "296a972f-666a-44a1-a3df-c9c28a1f56c0", "name": "bad_request", "message": "init_image: is required" } } } }, "400FromUpscale": { "description": "One or more parameters were invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "id": "296a972f-666a-44a1-a3df-c9c28a1f56c0", "name": "bad_request", "message": "image: is required" } } } } }, "headers": { "Content-Length": { "required": true, "schema": { "type": "integer" } }, "Content-Type": { "required": true, "schema": { "enum": [ "application/json", "image/png" ], "type": "string" } }, "Finish-Reason": { "schema": { "$ref": "#/components/schemas/FinishReason" } }, "Seed": { "example": 3817857576, "schema": { "example": 787078103, "type": "integer" }, "description": "The seed used to generate the image. This header is only present when the `Accept` is set to `image/png`. Otherwise it is returned in the response body." } } }, "x-tagGroups": [ { "name": "Stable Image", "tags": [ "Generate", "Upscale", "Edit", "Control", "Results" ] }, { "name": "3D & Video", "tags": [ "3D", "Image-to-Video" ] }, { "name": "Version 1", "tags": [ "SDXL 1.0 & SD1.6", "Engines", "User" ] } ] }