> ## Documentation Index > Fetch the complete documentation index at: https://docs.stability.ai/llms.txt > Use this file to discover all available pages before exploring further. # Image-to-image with a mask > 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. > NOTE: Only **Version 1** engines will work with this endpoint. ## OpenAPI ````yaml /openapi-v1.json post /v1/generation/{engine_id}/image-to-image/masking openapi: 3.0.3 info: termsOfService: https://platform.stability.ai/docs/terms-of-service description: > Welcome to the official Stability AI REST API! #### Authentication You will need your [Stability API key](https://platform.stability.ai/dashboard/api-keys) in order to make requests to this API. Make sure you never share your API key with anyone, and you never commit it to a public repository. Include this key in the `Authorization` header of your requests. #### Rate limiting This API is rate-limited to 150 requests every 10 seconds. If you exceed this limit, you will receive a `429` response. If you find this limit too restrictive, please reach out to us via email at [platform@stability.ai](mailto:platform@stability.ai). #### Support Check our [Status Page](https://stabilityai.instatus.com/) to view the current health of our REST/gRPC APIs. If you run into issues, please reach out to us: - [Support Form](https://platform.stability.ai/support) - [platform@stability.ai](mailto:platform@stability.ai) - [Discord](https://discord.com/channels/1002292111942635562/1042896447311454361) title: Stability.ai REST API version: v1 x-logo: altText: Stability.ai REST API url: /docs/StabilityLogo.png servers: - url: https://api.stability.ai security: [] tags: - 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 description: Generate images using SDXL 1.0. paths: /v1/generation/{engine_id}/image-to-image/masking: post: tags: - SDXL 1.0 summary: Image-to-image with a mask 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. > NOTE: Only **Version 1** engines will work with this endpoint. operationId: masking 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: - label: Python lang: python source: | import base64 import os import requests engine_id = "stable-diffusion-xl-1024-v1-0" api_host = os.getenv('API_HOST', 'https://api.stability.ai') api_key = os.getenv("STABILITY_API_KEY") if api_key is None: raise Exception("Missing Stability API key.") response = requests.post( f"{api_host}/v1/generation/{engine_id}/image-to-image/masking", headers={ "Accept": 'application/json', "Authorization": f"Bearer {api_key}" }, files={ 'init_image': open("../init_image.png", 'rb'), 'mask_image': open("../mask_image_black.png", 'rb'), }, data={ "mask_source": "MASK_IMAGE_BLACK", "text_prompts[0][text]": "A large spiral galaxy with a bright central bulge and a ring of stars around it", "cfg_scale": 7, "clip_guidance_preset": "FAST_BLUE", "samples": 1, "steps": 30, } ) if response.status_code != 200: raise Exception("Non-200 response: " + str(response.text)) data = response.json() for i, image in enumerate(data["artifacts"]): with open(f"./out/v1_img2img_masking_{i}.png", "wb") as f: f.write(base64.b64decode(image["base64"])) - label: TypeScript lang: javascript source: > import fetch from 'node-fetch' import FormData from 'form-data' import fs from 'node:fs' const engineId = 'stable-diffusion-xl-1024-v1-0' const apiHost = process.env.API_HOST ?? 'https://api.stability.ai' const apiKey = process.env.STABILITY_API_KEY if (!apiKey) throw new Error('Missing Stability API key.') // NOTE: This example is using a NodeJS FormData library. Browser // implementations should use their native FormData class. React Native // implementations should also use their native FormData class. const formData = new FormData() formData.append('init_image', fs.readFileSync('../init_image.png')) formData.append('mask_image', fs.readFileSync('../mask_image_black.png')) formData.append('mask_source', 'MASK_IMAGE_BLACK') formData.append( 'text_prompts[0][text]', 'A large spiral galaxy with a bright central bulge and a ring of stars around it' ) formData.append('cfg_scale', '7') formData.append('clip_guidance_preset', 'FAST_BLUE') formData.append('samples', 1) formData.append('steps', 30) const response = await fetch( `${apiHost}/v1/generation/${engineId}/image-to-image/masking`, { method: 'POST', headers: { ...formData.getHeaders(), Accept: 'application/json', Authorization: `Bearer ${apiKey}`, }, body: formData, } ) if (!response.ok) { throw new Error(`Non-200 response: ${await response.text()}`) } interface GenerationResponse { artifacts: Array<{ base64: string seed: number finishReason: string }> } const responseJSON = (await response.json()) as GenerationResponse responseJSON.artifacts.forEach((image, index) => { fs.writeFileSync( `out/v1_img2img_masking_${index}.png`, Buffer.from(image.base64, 'base64') ) }) - label: Go 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-xl-1024-v1-0\"\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" - label: cURL lang: bash source: > #!/bin/sh set -e if [ -z "$STABILITY_API_KEY" ]; then echo "STABILITY_API_KEY environment variable is not set" exit 1 fi OUTPUT_FILE=./out/v1_img2img_masking.png BASE_URL=${API_HOST:-https://api.stability.ai} URL="$BASE_URL/v1/generation/stable-diffusion-xl-1024-v1-0/image-to-image/masking" curl -f -sS -X POST "$URL" \ -H 'Content-Type: multipart/form-data' \ -H 'Accept: image/png' \ -H "Authorization: Bearer $STABILITY_API_KEY" \ -F 'init_image=@"../init_image.png"' \ -F 'mask_image=@"../mask_image_black.png"' \ -F 'mask_source=MASK_IMAGE_BLACK' \ -F 'text_prompts[0][text]=A large spiral galaxy with a bright central bulge and a ring of stars around it' \ -F 'cfg_scale=7' \ -F 'clip_guidance_preset=FAST_BLUE' \ -F 'samples=1' \ -F 'steps=30' \ -o "$OUTPUT_FILE" components: parameters: 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 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 schemas: 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' InitImage: x-go-type: '[]byte' type: string description: Image used to initialize the diffusion process, in lieu of random noise. 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: - `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 - `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 - `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 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 TextPrompts: description: >- An array of text prompts to use for generation. Due to how arrays are represented in `multipart/form-data` requests, prompts must adhere to the format `text_prompts[index][text|weight]`, where `index` is some integer used to tie the text and weight together. While `index` does not have to be sequential, duplicate entries will override previous entries, so it is recommended to use sequential indices. Given a text prompt with the text `A lighthouse on a cliff` and a weight of `0.5`, it would be represented as: ``` text_prompts[0][text]: "A lighthouse on a cliff" text_prompts[0][weight]: 0.5 ``` To add another prompt to that request simply provide the values under a new `index`: ``` text_prompts[0][text]: "A lighthouse on a cliff" text_prompts[0][weight]: 0.5 text_prompts[1][text]: "land, ground, dirt, grass" text_prompts[1][weight]: -0.9 ``` type: array items: $ref: '#/components/schemas/TextPrompt' minItems: 1 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 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 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. This list of style presets is subject to change. Extras: type: object description: >- Extra parameters passed to the engine. These parameters are used for in-development or experimental features and may change without warning, so please use with caution. 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' 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 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 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 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' FinishReason: type: string description: >- The result of the generation process. - `SUCCESS` indicates success - `ERROR` indicates an error - `CONTENT_FILTERED` indicates the result affected by the content filter and may be blurred. This 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 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' 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. securitySchemes: STABILITY_API_KEY: type: http scheme: bearer description: >- Your [Stability API key](https://platform.stability.ai/dashboard/api-keys), sent as a bearer token in the `Authorization` header. ````