> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yelu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate an image

> Generate images from a text prompt with the OpenAI-compatible Yelu Images API.

Generates one or more images from a text prompt. Supported fields, sizes, output formats, and quality controls depend on the selected image model.

## Endpoint

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://api.yelu.ai/v1/images/generations
```

## Headers

<ParamField header="Authorization" type="string" required>
  API key using the format `Bearer $YELU_API_KEY`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request body

<ParamField body="model" type="string" required>
  An image-capable model ID available to your account.
</ParamField>

<ParamField body="prompt" type="string" required>
  Description of the image to create. Prompt length limits are model-specific.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Number of images to generate when supported. Validate this value to control cost.
</ParamField>

<ParamField body="size" type="string">
  Requested dimensions such as `1024x1024`. Accepted values depend on the model.
</ParamField>

<ParamField body="quality" type="string">
  Model-specific quality setting such as `standard` or `hd`, when supported.
</ParamField>

<ParamField body="style" type="string">
  Model-specific style control, when supported.
</ParamField>

<ParamField body="response_format" type="string" default="url">
  `url` or `b64_json`, subject to model support. URLs can expire; download them promptly.
</ParamField>

<ParamField body="user" type="string">
  Stable, non-sensitive end-user identifier for abuse monitoring and attribution.
</ParamField>

## Response

<ResponseField name="created" type="integer" required>
  Unix timestamp for generation.
</ResponseField>

<ResponseField name="data" type="array" required>
  Generated image objects. Each object contains `url` or `b64_json`, and can include `revised_prompt`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://api.yelu.ai/v1/images/generations \
    -H "Authorization: Bearer $YELU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "dall-e-3",
      "prompt": "An isometric illustration of a calm API gateway routing beams of light between model clouds, violet and indigo palette",
      "size": "1024x1024",
      "n": 1,
      "response_format": "url"
    }'
  ```

  ```javascript JavaScript (Fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.yelu.ai/v1/images/generations', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.YELU_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'dall-e-3',
      prompt: 'An isometric illustration of a calm API gateway routing beams of light between model clouds, violet and indigo palette',
      size: '1024x1024',
      n: 1,
      response_format: 'url',
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  console.log((await response.json()).data[0].url);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.post(
      "https://api.yelu.ai/v1/images/generations",
      headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
      json={
          "model": "dall-e-3",
          "prompt": "An isometric illustration of a calm API gateway routing beams of light between model clouds, violet and indigo palette",
          "size": "1024x1024",
          "n": 1,
          "response_format": "url",
      },
      timeout=180,
  )
  response.raise_for_status()
  print(response.json()["data"][0]["url"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "created": 1783900800,
    "data": [
      {
        "url": "https://cdn.example.invalid/generated/image-01.png",
        "revised_prompt": "An isometric technical illustration of a reliable AI gateway..."
      }
    ]
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": {
      "message": "The requested size is not supported by this model.",
      "type": "invalid_request_error",
      "param": "size",
      "code": "invalid_value"
    }
  }
  ```
</ResponseExample>

## Error codes

| Status      | Code or type            | Meaning                                                    |
| ----------- | ----------------------- | ---------------------------------------------------------- |
| `400`       | `invalid_request_error` | Invalid prompt, size, quality, count, or model capability. |
| `401`       | `authentication_error`  | Missing or invalid API key.                                |
| `403`       | `permission_denied`     | Image generation or the selected model is not enabled.     |
| `404`       | `model_not_found`       | The image model is unavailable.                            |
| `429`       | `rate_limit_error`      | Request limit reached.                                     |
| `500`–`504` | `server_error`          | Temporary gateway or provider generation failure.          |

<Note>
  The response URL above uses the reserved `.invalid` domain to illustrate the response shape. Real successful responses contain a provider or Yelu delivery URL, or base64 image data when requested and supported.
</Note>