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

# 生成图像

> 使用 Theo Create 引擎根据文本提示生成图像。

根据文本提示生成一张或多张图像。这是一个同步端点——图像会直接在响应中返回。

## 身份验证

需要 Bearer 令牌。参见[身份验证](/api-reference/authentication)。

## 请求体

<ParamField body="prompt" type="string" required>
  要生成的图像的文本描述。
</ParamField>

<ParamField body="style" type="string">
  视觉风格提示（例如 `"photorealistic"`、`"illustration"`、`"watercolor"`、`"3d-render"`）。会附加到提示词中传给图像引擎。
</ParamField>

<ParamField body="aspect_ratio" type="string">
  宽高比（例如 `"1:1"`、`"16:9"`、`"9:16"`、`"4:3"`）。默认为引擎的原生比例。
</ParamField>

<ParamField body="count" type="integer" default="1">
  要生成的图像数量（1–4）。
</ParamField>

## 请求示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/images \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "A minimalist tech logo, blue and white",
      "style": "photorealistic",
      "aspect_ratio": "1:1",
      "count": 2
    }'
  ```

  ```typescript SDK theme={null}
  const res = await theo.images({
    prompt: "A minimalist tech logo, blue and white",
    style: "photorealistic",
    aspect_ratio: "1:1",
    count: 2,
  });

  for (const img of res.images) {
    console.log(img.url, img.engine);
  }
  ```
</CodeGroup>

## 响应

<ResponseField name="id" type="string">
  唯一的图像生成 ID（前缀为 `img_`）。
</ResponseField>

<ResponseField name="created" type="string">
  ISO 8601 时间戳。
</ResponseField>

<ResponseField name="images" type="object[]">
  生成的图像数组。

  <Expandable title="Image object">
    <ResponseField name="url" type="string | null">托管的图像 URL。</ResponseField>
    <ResponseField name="engine" type="string">生成该图像的 Theo 引擎子系统（例如 `"theo-vision"`）。</ResponseField>
    <ResponseField name="model" type="string">Theo 模型 ID（例如 `"theo-1-create"`）。</ResponseField>
    <ResponseField name="prompt" type="string">实际使用的提示词（可能包含风格/比例方面的增强内容）。</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  <Expandable title="Usage object">
    <ResponseField name="cost_cents" type="number">花费的美分数。</ResponseField>
  </Expandable>
</ResponseField>

### 响应示例

```json theme={null}
{
  "id": "img_abc123",
  "created": "2026-04-10T12:00:00Z",
  "images": [
    {
      "url": "https://artifacts.hitheo.ai/img/abc123-1.png",
      "engine": "theo-vision",
      "model": "theo-1-create",
      "prompt": "A minimalist tech logo, blue and white Style: photorealistic. Aspect ratio: 1:1."
    },
    {
      "url": "https://artifacts.hitheo.ai/img/abc123-2.png",
      "engine": "theo-vision",
      "model": "theo-1-create",
      "prompt": "A minimalist tech logo, blue and white Style: photorealistic. Aspect ratio: 1:1."
    }
  ],
  "usage": { "cost_cents": 0.08 }
}
```

## 错误

| 状态码 | 代码 | 描述 |
| - | - | - |
| 400 | `missing_prompt` | 缺少必填的 `prompt` |
| 401 | `invalid_api_key` | API 密钥缺失或无效 |
| 429 | `rate_limit_exceeded` | 请求次数过多 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.