> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenAI Image Generations
> Generate one standard image as base64 with a Completion API key.
Generate one standard image with `POST /openai/{region}/v1/images/generations`. Send a prompt and an image model from your workspace. The response returns the image as `b64_json`.
The request uses the same Completion API scope as [OpenAI Chat Completions](/en/developer/completion-api/openai) and [OpenAI Responses](/en/developer/completion-api/openai-responses). Chat tools, workflow nodes, and Agent API `imageGeneration` are separate surfaces.
## Before You Start
* **API key**: Create a [personal API key](/en/using-langdock/account/personal-api-keys) or ask your workspace admin for a workspace API key with the Completion API scope.
## Base URL
```
https://api.langdock.com/openai/{region}/v1/images/generations
```
**Dedicated deployments**
Replace `api.langdock.com` with `/api/public` in all requests.
The `{region}` path value must be `eu` or `us`. This route does not accept `global`.
## Parameters
The request body is a strict object. Extra fields return `400`.
| Parameter | Description |
| - | - |
| `model` | Required. The image generation model ID from your workspace. Visible image models in the request region with an API-available deployment are accepted. `GET /openai/{region}/v1/models` lists chat models, not image models. An unknown model returns `400` with the image model IDs available in that region. If the region has none, the `400` says so. |
| `prompt` | Required. The image description. |
| `n` | Optional. Must be `1` if you send it. |
| `size` | Optional. `auto` (default), `1024x1024`, `1536x1024`, or `1024x1536`. `auto` and `1024x1024` map to square, `1536x1024` to landscape, and `1024x1536` to portrait. |
| `quality` | Optional. `auto`, `low`, `medium`, or `high`. Langdock forwards the value to the image model. Not every image model uses it. |
| `response_format` | Optional. `b64_json` only. |
| `user` | Optional. Accepted for OpenAI compatibility. |
## Response
A successful response is JSON with `created` and `data`. `data` contains one object with `b64_json` and, when the model returns one, `revised_prompt`. The HTTP body has no `usage` object. The `ld-model-id` response header repeats the model ID.
Generation times out after 60 seconds. A timeout returns `504` with `The model did not respond in time. Please retry.`
## Differences from the OpenAI API
* One image per request. `n` other than `1` is rejected.
* `response_format` is `b64_json` only. URL output is not supported.
* HD / high-resolution generation is not supported.
* There is no public `/v1/images/edits` route.
## Using the OpenAI Python library
Set Langdock as the base URL and call `images.generate`:
```python theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://api.langdock.com/openai/eu/v1",
api_key="",
)
image = client.images.generate(
model="your-image-model-id",
prompt="A lighthouse at dusk",
size="1024x1024",
response_format="b64_json",
)
print(image.data[0].b64_json)
```
## Rate limits
The default limits are **500 RPM** (requests per minute) and **150,000 TPM** (tokens per minute).
* RPM is enforced per workspace, model, and API key.
* TPM is shared by all API keys using the same model in a workspace.
* On dedicated deployments, admins can configure custom limits per model in **Settings > Workspace > Products > API**.
A rate-limited request returns `429 Too Many Requests`. Successful and rate-limited responses include `x-ratelimit-limit-requests`, `x-ratelimit-limit-tokens`, `x-ratelimit-remaining-requests`, and `x-ratelimit-remaining-tokens`.
Personal API key usage counts toward the member's effective personal budget and the workspace spend limit together with chat and agent usage. Workspace API key usage counts toward the workspace API spend limit. Image generation calls are billed as image generation usage. See [Personal API keys](/en/using-langdock/account/personal-api-keys) and [Pricing](/en/admin/billing/pricing#api).
Browser and CORS integrations are not supported. Keep API keys server-side and call the endpoint from a server, CLI, or local development tool. See [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
## OpenAPI
````yaml POST /openai/{region}/v1/images/generations
openapi: 3.0.0
info:
title: Langdock API
version: 3.0.0
servers:
- url: https://api.langdock.com
description: Production
security:
- bearerAuth: []
paths:
/openai/{region}/v1/images/generations:
post:
tags:
- Images
summary: Generates one standard image as base64.
description: >-
Generates one standard-resolution image with a Completion API key.
Returns b64_json only. Does not support n other than 1, URL output, HD,
or image edits.
operationId: createImage
parameters:
- name: region
in: path
required: true
description: The region of the API to use. Must be eu or us.
schema:
type: string
enum:
- eu
- us
default: eu
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- model
- prompt
properties:
model:
type: string
minLength: 1
description: >-
Image generation model ID from your workspace. GET
/openai/{region}/v1/models lists chat models, not image
models.
prompt:
type: string
minLength: 1
description: The image description.
'n':
type: integer
enum:
- 1
description: Number of images. Only 1 is supported.
size:
type: string
enum:
- auto
- 1024x1024
- 1536x1024
- 1024x1536
default: auto
description: >-
Output size. auto and 1024x1024 map to square, 1536x1024 to
landscape, and 1024x1536 to portrait.
quality:
type: string
enum:
- auto
- low
- medium
- high
description: >-
Quality hint forwarded to the image model. Not every image
model uses it.
response_format:
type: string
enum:
- b64_json
description: Response format. Only b64_json is supported.
user:
type: string
description: >-
Optional end-user identifier. Accepted for OpenAI
compatibility.
example:
model: your-image-model-id
prompt: A lighthouse at dusk
'n': 1
size: 1024x1024
response_format: b64_json
responses:
'200':
description: OK
headers:
ld-model-id:
description: The image model ID used for the request.
schema:
type: string
content:
application/json:
schema:
type: object
required:
- created
- data
properties:
created:
type: integer
description: Unix timestamp in seconds.
data:
type: array
minItems: 1
maxItems: 1
items:
type: object
required:
- b64_json
properties:
b64_json:
type: string
description: Base64-encoded image.
revised_prompt:
type: string
description: Revised prompt when the model returns one.
example:
created: 1721722200
data:
- b64_json: >-
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==
revised_prompt: A coastal lighthouse at dusk, warm lantern light.
'400':
description: >-
Invalid fields, an unavailable image model, or no image models in
the region.
'401':
description: Missing, invalid, or expired API key.
'403':
description: API key without the Completion API scope.
'429':
description: Usage or rate limit exceeded.
'500':
description: Internal server or upstream provider error.
'504':
description: The model did not respond in time. Please retry.
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.