> For the complete documentation index, see [llms.txt](https://docs.nexos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexos.ai/gateway-api/images.md).

# Images

Generate or edit images from image or text input.

## Create image

> Generate images from a text prompt.

```json
{"openapi":"3.0.0","info":{"title":"Nexos AI Public API Production","version":"1.0.0"},"tags":[{"name":"Images","description":"Generate or edit images from image or text input."}],"servers":[{"url":"https://api.nexos.ai"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Authenticate by sending your nexos API key in the `X-Api-Key` header (e.g. `X-Api-Key: user-...` for a user key or `X-Api-Key: team-...` for a team key). This is an alternative to the `Authorization: Bearer` scheme. If both `X-Nexos-Key` and `X-Api-Key` are sent, `X-Nexos-Key` takes precedence."}},"schemas":{"ImagesGenerationsRequest":{"type":"object","additionalProperties":false,"properties":{"prompt":{"description":"A text description of the desired image(s).","type":"string"},"model":{"type":"string"},"n":{"type":"integer","minimum":1,"maximum":10,"nullable":true,"description":"The number of images to generate. Must be between 1 and 10."},"quality":{"description":"The quality of the generated images. Supported values depend on the model: GPT Image models accept `low`, `medium`, `high`, and `auto`; `standard` and `hd` are DALL-E values and are rejected by GPT Image models.\n","type":"string","enum":["auto","low","medium","high","standard","hd"],"nullable":true},"response_format":{"description":"The format of the generated images. The currently available models (GPT Image, Imagen) ignore this parameter and always return base64-encoded images (`b64_json`); `url` only applies to models that support hosted image URLs.\n","type":"string","enum":["url","b64_json"],"nullable":true},"size":{"description":"The size of the generated images. Supported values depend on the model: GPT Image models accept `1024x1024`, `1536x1024`, `1024x1536`, and `auto`; the remaining values are DALL-E sizes.\n","type":"string","enum":["auto","1024x1024","1536x1024","1024x1536","256x256","512x512","1792x1024","1024x1792"],"nullable":true},"style":{"description":"The style of the generated images. DALL-E parameter; accepted but ignored by GPT Image models.","type":"string","enum":["vivid","natural"],"nullable":true}},"required":["prompt","model"]},"ImagesResponseBody":{"type":"object","properties":{"created":{"type":"integer","description":"The Unix timestamp (in seconds) of when the images were created.\n"},"data":{"type":"array","items":{"type":"object","properties":{"b64_json":{"type":"string","description":"The base64-encoded JSON of the generated image. Always returned by GPT Image models,\notherwise returned if response_format is b64_json.\n"},"revised_prompt":{"type":"string","description":"The prompt that was used to generate the image, if there was any revision to the prompt.\n"},"url":{"type":"string","description":"The URL of the generated image, if response_format is url. Not returned by GPT Image models.\n"}}}},"background":{"type":"string","description":"The background setting of the generated images. Returned by GPT Image models."},"output_format":{"type":"string","description":"The output format of the generated images. Returned by GPT Image models."},"quality":{"type":"string","description":"The quality of the generated images. Returned by GPT Image models."},"size":{"type":"string","description":"The size of the generated images. Returned by GPT Image models."},"provider":{"type":"string","description":"The upstream provider that served the request (e.g. `vertex-ai`). Returned for some providers."},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"input_tokens_details":{"type":"object","properties":{"image_tokens":{"type":"integer"},"text_tokens":{"type":"integer"}}},"output_tokens":{"type":"integer"},"output_tokens_details":{"type":"object","properties":{"image_tokens":{"type":"integer"},"text_tokens":{"type":"integer"}}},"total_tokens":{"type":"integer"},"nexos_credits_cost":{"type":"number","format":"double","description":"Cost of the request in nexos credits."}}}},"required":["created","data"]}},"responses":{"ImagesResponse":{"description":"Represents an image response returned by model, based on the provided input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImagesResponseBody"}}}},"OutOfCredits":{"description":"The company has run out of AI credits. Returned when the company's budget limit has been reached.\n","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}}}}}}}}},"paths":{"/v1/images/generations":{"post":{"operationId":"post-images-generations-v1","summary":"Create image","tags":["Images"],"description":"Generate images from a text prompt.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImagesGenerationsRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/ImagesResponse"},"400":{"description":"Invalid request data."},"402":{"$ref":"#/components/responses/OutOfCredits"},"500":{"description":"Server error."}}}}}}
```

## Edit images

> Edit or extend images based on image and text input, using GPT Image models.

```json
{"openapi":"3.0.0","info":{"title":"Nexos AI Public API Production","version":"1.0.0"},"tags":[{"name":"Images","description":"Generate or edit images from image or text input."}],"servers":[{"url":"https://api.nexos.ai"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Authenticate by sending your nexos API key in the `X-Api-Key` header (e.g. `X-Api-Key: user-...` for a user key or `X-Api-Key: team-...` for a team key). This is an alternative to the `Authorization: Bearer` scheme. If both `X-Nexos-Key` and `X-Api-Key` are sent, `X-Nexos-Key` takes precedence."}},"schemas":{"ImagesEditsRequest":{"type":"object","properties":{"image":{"description":"The image(s) to edit. Send one `image` part for a single image, or repeated\n`image[]` parts for multiple images (up to 16). Each image must be a png,\nwebp, or jpg file less than 50MB. Total request size is limited to 100MB.\n","type":"array","maxItems":16,"items":{"type":"string","format":"binary"}},"mask":{"description":"An additional image whose fully transparent areas (e.g. where alpha is zero)\nindicate where `image` should be edited. If multiple images are provided, the\nmask is applied to the first image. Must be a valid PNG file, less than 4MB,\nand have the same dimensions as the first image.\n","type":"string","format":"binary"},"prompt":{"description":"A text description of the desired image(s). The maximum length is 32000 characters.","type":"string","maxLength":32000},"model":{"type":"string"},"n":{"type":"integer","minimum":1,"maximum":10,"nullable":true,"description":"The number of images to generate. Must be between 1 and 10."},"size":{"description":"The size of the generated images. The standard sizes are `1024x1024`, `1536x1024`, and `1024x1536`; `auto` lets the model pick. GPT Image 2.5 models also accept arbitrary `WIDTHxHEIGHT` strings (both dimensions divisible by 16, aspect ratio between 1:3 and 3:1, max 3840x2160).\n","type":"string","nullable":true},"quality":{"description":"The quality of the generated images. GPT Image models support `low`, `medium`, and `high`; GPT Image 2.5 models additionally support `xhigh` and `max`. Defaults to `auto`.\n","type":"string","enum":["low","medium","high","xhigh","max","auto"],"nullable":true},"background":{"description":"The background of the generated image(s). `transparent` requires `output_format` png or webp. Defaults to `auto`.\n","type":"string","enum":["transparent","opaque","auto"],"nullable":true},"output_format":{"description":"The format of the generated images. Defaults to `png`.","type":"string","enum":["png","jpeg","webp"],"nullable":true},"output_compression":{"description":"The compression level (0-100%) for the generated images. Only applies to the `webp` and `jpeg` output formats. Defaults to 100.\n","type":"integer","minimum":0,"maximum":100,"nullable":true},"input_fidelity":{"description":"Control how much effort the model exerts to match the style and features, especially facial features, of input images. Defaults to `low`.\n","type":"string","enum":["low","high"],"nullable":true},"user":{"description":"A unique identifier representing your end-user, which can help to monitor and detect abuse.","type":"string"},"stream":{"description":"Edit the image in streaming mode. When true, the response is sent as server-sent events (`text/event-stream`): `image_edit.partial_image` events (see `partial_images`) followed by a final `image_edit.completed` event carrying the edited image and token usage. Defaults to false.\n","type":"boolean","nullable":true},"partial_images":{"description":"The number of partial images to generate in streaming mode, between 0 and 3. Only used when `stream` is true. When 0, the response is a single image sent in one streaming event. The final image may arrive before all partial images if it is generated more quickly.\n","type":"integer","minimum":0,"maximum":3,"nullable":true}},"required":["image","prompt","model"]},"ImagesResponseBody":{"type":"object","properties":{"created":{"type":"integer","description":"The Unix timestamp (in seconds) of when the images were created.\n"},"data":{"type":"array","items":{"type":"object","properties":{"b64_json":{"type":"string","description":"The base64-encoded JSON of the generated image. Always returned by GPT Image models,\notherwise returned if response_format is b64_json.\n"},"revised_prompt":{"type":"string","description":"The prompt that was used to generate the image, if there was any revision to the prompt.\n"},"url":{"type":"string","description":"The URL of the generated image, if response_format is url. Not returned by GPT Image models.\n"}}}},"background":{"type":"string","description":"The background setting of the generated images. Returned by GPT Image models."},"output_format":{"type":"string","description":"The output format of the generated images. Returned by GPT Image models."},"quality":{"type":"string","description":"The quality of the generated images. Returned by GPT Image models."},"size":{"type":"string","description":"The size of the generated images. Returned by GPT Image models."},"provider":{"type":"string","description":"The upstream provider that served the request (e.g. `vertex-ai`). Returned for some providers."},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"input_tokens_details":{"type":"object","properties":{"image_tokens":{"type":"integer"},"text_tokens":{"type":"integer"}}},"output_tokens":{"type":"integer"},"output_tokens_details":{"type":"object","properties":{"image_tokens":{"type":"integer"},"text_tokens":{"type":"integer"}}},"total_tokens":{"type":"integer"},"nexos_credits_cost":{"type":"number","format":"double","description":"Cost of the request in nexos credits."}}}},"required":["created","data"]},"ImageEditStreamEvent":{"description":"Server-sent events returned when an image edit request runs with `stream: true`.\nZero to three `image_edit.partial_image` events are followed by a final\n`image_edit.completed` event carrying the edited image and token usage.\n","oneOf":[{"type":"object","required":["type","b64_json","created_at","size","quality","background","output_format","partial_image_index"],"properties":{"type":{"type":"string","enum":["image_edit.partial_image"],"description":"The type of the event. Always `image_edit.partial_image`."},"b64_json":{"type":"string","description":"Base64-encoded partial image data, suitable for rendering as an image."},"created_at":{"type":"integer","description":"The Unix timestamp (in seconds) when the event was created."},"size":{"type":"string","description":"The image dimensions as a `WIDTHxHEIGHT` string."},"quality":{"type":"string","enum":["low","medium","high","xhigh","max","auto"],"description":"The quality setting for the requested image."},"background":{"type":"string","enum":["transparent","opaque","auto"],"description":"The background setting for the requested image."},"output_format":{"type":"string","enum":["png","webp","jpeg"],"description":"The output format for the requested image."},"partial_image_index":{"type":"integer","description":"0-based index of the partial image."}}},{"type":"object","required":["type","b64_json","created_at","size","quality","background","output_format","usage"],"properties":{"type":{"type":"string","enum":["image_edit.completed"],"description":"The type of the event. Always `image_edit.completed`."},"b64_json":{"type":"string","description":"Base64-encoded final edited image data, suitable for rendering as an image."},"created_at":{"type":"integer","description":"The Unix timestamp (in seconds) when the event was created."},"size":{"type":"string","description":"The image dimensions as a `WIDTHxHEIGHT` string."},"quality":{"type":"string","enum":["low","medium","high","xhigh","max","auto"],"description":"The quality setting for the edited image."},"background":{"type":"string","enum":["transparent","opaque","auto"],"description":"The background setting for the edited image."},"output_format":{"type":"string","enum":["png","webp","jpeg"],"description":"The output format for the edited image."},"usage":{"type":"object","required":["total_tokens","input_tokens","output_tokens","input_tokens_details"],"properties":{"total_tokens":{"type":"integer","description":"The total number of tokens (images and text) used for the image edit."},"input_tokens":{"type":"integer","description":"The number of tokens (images and text) in the input prompt."},"output_tokens":{"type":"integer","description":"The number of image tokens in the output image."},"input_tokens_details":{"type":"object","required":["text_tokens","image_tokens"],"properties":{"text_tokens":{"type":"integer","description":"The number of text tokens in the input prompt."},"image_tokens":{"type":"integer","description":"The number of image tokens in the input prompt."}}},"nexos_credits_cost":{"type":"number","format":"double","description":"Cost of the request in nexos credits."}}}}}]}},"responses":{"OutOfCredits":{"description":"The company has run out of AI credits. Returned when the company's budget limit has been reached.\n","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}}}}}}}}},"paths":{"/v1/images/edits":{"post":{"operationId":"post-images-edits-v1","summary":"Edit images","tags":["Images"],"description":"Edit or extend images based on image and text input, using GPT Image models.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ImagesEditsRequest"}}}},"responses":{"200":{"description":"The edited image(s) — a JSON object, or a stream of events when `stream: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImagesResponseBody"}},"text/event-stream":{"schema":{"$ref":"#/components/schemas/ImageEditStreamEvent"}}}},"400":{"description":"Invalid request data."},"402":{"$ref":"#/components/responses/OutOfCredits"},"500":{"description":"Server error."}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexos.ai/gateway-api/images.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.