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

# 文生图

> 从 prompt 生成图片的标准路径

文生图是当前图片 API 的稳定主线：输入 `prompt`，选择 `model`，返回图片 URL 或 base64。不同上游模型内部可能走不同协议，但客户侧优先按 OpenAI-compatible 的图片生成格式接入。

<Warning>图片生成建议由你的后端调用 Tapapi。不要把 `sk-` 开头的 Key 放到前端页面、移动端包体或公开工作流模板里。</Warning>

## 推荐路径

| 你的情况             | 推荐                                                   |
| ---------------- | ---------------------------------------------------- |
| 已有 OpenAI SDK 代码 | 用 [OpenAI 兼容路径](/image-generation/openai-compatible) |
| 新写 HTTP 调用       | 用 `POST /v1/images/generations`                      |
| 需要模型私有参数         | 先看 [高级路径](/image-generation/advanced) 的当前边界          |

## Endpoint

```text theme={null}
POST https://tapapi.ai/v1/images/generations
```

## 最小请求

```bash theme={null}
curl https://tapapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "a product photo of a white ceramic mug on a clean desk",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
```

## SDK 示例

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-xxx",
      base_url="https://tapapi.ai/v1",
  )

  response = client.images.generate(
      model="z-image-turbo",
      prompt="a clean ecommerce product photo of a white ceramic mug",
      n=1,
      size="1024x1024",
      response_format="url",
  )

  first = response.data[0]
  print(first.url or first.b64_json)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "sk-xxx",
    baseURL: "https://tapapi.ai/v1",
  });

  const response = await client.images.generate({
    model: "z-image-turbo",
    prompt: "a clean ecommerce product photo of a white ceramic mug",
    n: 1,
    size: "1024x1024",
    response_format: "url",
  });

  const first = response.data?.[0];
  console.log(first?.url ?? first?.b64_json);
  ```
</CodeGroup>

## 常用字段

| 字段                | 类型      |  必填 | 说明                                          |
| ----------------- | ------- | :-: | ------------------------------------------- |
| `model`           | string  |  ✅  | 模型名，以控制台和模型详情页为准                            |
| `prompt`          | string  |  ✅  | 图片生成提示词                                     |
| `n`               | integer |  —  | 生成张数，默认 1；不同模型支持范围不同                        |
| `size`            | string  |  —  | 例如 `1024x1024`、`1536x1024`；不要写成 `1024×1024` |
| `quality`         | string  |  —  | 仅部分模型支持                                     |
| `response_format` | string  |  —  | `url` 或 `b64_json`                          |
| `output_format`   | string  |  —  | 仅部分模型支持，例如 `png`、`jpeg`、`webp`              |

## 返回结果

```json theme={null}
{
  "created": 1780000000,
  "data": [
    {
      "url": "https://tapapi.ai/img-proxy/..."
    }
  ]
}
```

如果传 `response_format: "b64_json"`，返回项会使用 `b64_json` 字段。不同上游模型对返回格式的支持不完全一致，生产代码应同时兼容 `url` 和 `b64_json`。生产环境建议尽快把图片转存到自己的对象存储，详见 [输出图片保存](/image-generation/output-images)。

生产环境还需要检查：

| 检查项                       | 说明                                 |
| ------------------------- | ---------------------------------- |
| `data.length`             | 不能只看 HTTP 200；`data` 为空要按失败排查      |
| `metadata.tapapi_partial` | `n > 1` 时可能表示部分成功，需要按实际返回保存并补跑缺失图片 |
| `X-Oneapi-Request-Id`     | 保存响应头，排查上游失败、扣费和重试问题               |
| 图片下载状态                    | 拿到 URL 后仍要确认服务端下载和转存成功             |

<Warning>当前不要把 `image_urls` 当作 `/v1/images/generations` 的通用参数。图生图和多参考图仍在独立能力规划中，见 [图生图](/image-generation/image-to-image) 和 [多参考图](/image-generation/multi-reference)。</Warning>