> ## 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.

# 生成图像

> 通过兼容 OpenAI 的 Yelu Images API 根据文本提示生成图像。

根据文本 Prompt 生成一张或多张图像。字段、尺寸、输出格式与质量控制取决于所选模型。

## 端点

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

## 请求头

<ParamField header="Authorization" type="string" required>格式为 `Bearer $YELU_API_KEY`。</ParamField>
<ParamField header="Content-Type" type="string" required>必须为 `application/json`。</ParamField>

## 请求体

<ParamField body="model" type="string" required>账号可用的图像模型 ID。</ParamField>
<ParamField body="prompt" type="string" required>要生成的图像描述，长度限制取决于模型。</ParamField>
<ParamField body="n" type="integer" default="1">生成数量；并非所有模型都支持多张。</ParamField>
<ParamField body="size" type="string">例如 `1024x1024`；可接受值取决于模型。</ParamField>
<ParamField body="quality" type="string">模型支持时可使用 `standard` 或 `hd` 等值。</ParamField>
<ParamField body="style" type="string">模型特定风格控制。</ParamField>
<ParamField body="response_format" type="string" default="url">支持时可选 `url` 或 `b64_json`。URL 可能过期。</ParamField>
<ParamField body="user" type="string">稳定且不敏感的最终用户标识。</ParamField>

## 响应

<ResponseField name="created" type="integer" required>生成时间的 Unix 时间戳。</ResponseField>
<ResponseField name="data" type="array" required>图像结果；每项包含 `url` 或 `b64_json`，还可能包含 `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":"紫色与靛蓝配色的等距 AI Gateway 技术插画","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: '紫色与靛蓝配色的等距 AI Gateway 技术插画', 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": "紫色与靛蓝配色的等距 AI Gateway 技术插画", "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>

## 错误码

| 状态码         | 含义                     |
| ----------- | ---------------------- |
| `400`       | Prompt、尺寸、质量、数量或模型能力无效 |
| `401`       | Key 缺失或无效              |
| `403`       | 图像能力或模型未开启             |
| `404`       | 模型不可用                  |
| `429`       | 达到请求限制                 |
| `500`–`504` | 网关或供应商生成失败             |

<Note>成功返回的 URL 可能来自 Yelu 或上游供应商，通常有有效期，应及时下载并存入受控存储。</Note>