> ## 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. # Text-to-image > Generate an image from a text prompt. ### Using SDXL 1.0 Use `stable-diffusion-xl-1024-v1-0` as the `engine_id` of your request and pass in `height` & `width` as one of the following combinations: - 1024x1024 (default) - 1152x896 - 896x1152 - 1216x832 - 1344x768 - 768x1344 - 1536x640 - 640x1536 ### SDXL 1.0 Pricing When specifying 30 steps or fewer, generation costs 0.9 credits. When specifying above 30 steps, generation cost is determined using the following formula: `cost = 0.9 * (steps / 30)` ## OpenAPI ````yaml /openapi-v1.json post /v1/generation/{engine_id}/text-to-image 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}/text-to-image: post: tags: - SDXL 1.0 summary: Text-to-image description: > Generate an image from a text prompt. ### Using SDXL 1.0 Use `stable-diffusion-xl-1024-v1-0` as the `engine_id` of your request and pass in `height` & `width` as one of the following combinations: - 1024x1024 (default) - 1152x896 - 896x1152 - 1216x832 - 1344x768 - 768x1344 - 1536x640 - 640x1536 ### SDXL 1.0 Pricing When specifying 30 steps or fewer, generation costs 0.9 credits. When specifying above 30 steps, generation cost is determined using the following formula: `cost = 0.9 * (steps / 30)` operationId: textToImage 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: - 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}/text-to-image", headers={ "Content-Type": "application/json", "Accept": "application/json", "Authorization": f"Bearer {api_key}" }, json={ "text_prompts": [ { "text": "A lighthouse on a cliff" } ], "cfg_scale": 7, "height": 1024, "width": 1024, "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_txt2img_{i}.png", "wb") as f: f.write(base64.b64decode(image["base64"])) - label: TypeScript lang: javascript source: | import fetch from 'node-fetch' 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.') const response = await fetch( `${apiHost}/v1/generation/${engineId}/text-to-image`, { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json', Authorization: `Bearer ${apiKey}`, }, body: JSON.stringify({ text_prompts: [ { text: 'A lighthouse on a cliff', }, ], cfg_scale: 7, height: 1024, width: 1024, steps: 30, samples: 1, }), } ) 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_txt2img_${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\"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-xl-1024-v1-0\"\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" - label: cURL lang: bash source: > if [ -z "$STABILITY_API_KEY" ]; then echo "STABILITY_API_KEY environment variable is not set" exit 1 fi OUTPUT_FILE=./out/v1_txt2img.png BASE_URL=${API_HOST:-https://api.stability.ai} URL="$BASE_URL/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image" curl -f -sS -X POST "$URL" \ -H 'Content-Type: application/json' \ -H 'Accept: image/png' \ -H "Authorization: Bearer $STABILITY_API_KEY" \ --data-raw '{ "text_prompts": [ { "text": "A lighthouse on a cliff" } ], "cfg_scale": 7, "height": 1024, "width": 1024, "samples": 1, "steps": 30 }' \ -o "$OUTPUT_FILE" components: parameters: engineID: examples: default: value: stable-diffusion-xl-1024-v1-0 description: Stable Diffusion XL v1.0 in: path name: engine_id required: true 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 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: 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 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 TextPromptsForTextToImage: title: TextPrompts type: array items: $ref: '#/components/schemas/TextPrompt' minItems: 1 description: >- An array of text prompts to use for generation. 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": [ { "text": "A lighthouse on a cliff", "weight": 0.5 } ] ``` 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' 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 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. 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. ````