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