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

# Images

> 使用 gpt-image-1 进行图像生成、编辑与变体创建。

## 生成图片

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "A futuristic skyline at dusk",
    "size": "1024x1024"
  }'
```

使用 openai 官方 Python SDK（通过 `base_url` 指向 Rivus AI 网关）：

```python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://models.rivus.cn/v1",
    api_key="YOUR_API_KEY",
)

result = client.images.generate(
    model="gpt-image-1",
    prompt="A futuristic skyline at dusk",
    size="1024x1024",
)

# 默认返回图片 URL，可直接用于下载或在前端展示
print(result.data[0].url)
```

## 编辑图片

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-1" \
  -F "image=@base.png" \
  -F "mask=@mask.png" \
  -F "prompt=在天空中加入热气球"
```

## 创建变体

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/variations" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-1" \
  -F "image=@origin.png"
```

<Callout type="info">
  所有接口均支持 `n`、`quality`、`background` 等附加参数。若需返回 base64，可设置 `response_format`。
</Callout>


## OpenAPI

````yaml POST /v1/images/generations
openapi: 3.0.0
info:
  title: Gemini Images API
  description: Gemini 图像生成 API（Imagen & Gemini 图像模型）
  version: 1.0.0
servers:
  - url: https://models.rivus.cn
    description: Rivus AI 生产环境
security:
  - BearerAuth: []
paths:
  /v1/images/generations:
    post:
      tags:
        - Images
      summary: 生成图像（OpenAI 兼容）
      description: 使用 Imagen 或 Gemini 图像模型生成图片
      operationId: createImageGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - prompt
              properties:
                model:
                  type: string
                  description: 模型名称
                  enum:
                    - imagen-3.0-generate-001
                    - gemini-2.5-flash-image-preview
                    - gemini-3-pro-image-preview
                  example: gemini-3-pro-image-preview
                prompt:
                  type: string
                  description: 图像描述文本
                  maxLength: 4000
                  example: >-
                    A futuristic cityscape at sunset with flying cars, cyberpunk
                    style, highly detailed
                'n':
                  type: integer
                  description: 生成图片数量（Imagen 支持 1-4，Gemini 仅支持 1）
                  minimum: 1
                  maximum: 4
                  default: 1
                size:
                  type: string
                  description: 图像尺寸
                  enum:
                    - 1024x1024
                    - 1792x1024
                    - 1024x1792
                  default: 1024x1024
                  example: 1024x1024
                aspect_ratio:
                  type: string
                  description: 宽高比（优先级高于 size）
                  enum:
                    - '1:1'
                    - '16:9'
                    - '9:16'
                  example: '1:1'
                response_format:
                  type: string
                  description: 响应格式
                  enum:
                    - url
                    - b64_json
                  default: url
            examples:
              gemini-3-pro:
                summary: Gemini 3 Pro Image
                value:
                  model: gemini-3-pro-image-preview
                  prompt: A panda reading a book in the library, cinematic lighting
                  size: 1024x1024
                  response_format: b64_json
              imagen-3:
                summary: Imagen 3
                value:
                  model: imagen-3.0-generate-001
                  prompt: A serene mountain landscape at dawn
                  'n': 2
                  aspect_ratio: '16:9'
      responses:
        '200':
          description: 图像生成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
              example:
                created: 1762789802
                data:
                  - b64_json: >-
                      iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
components:
  schemas:
    ImageResponse:
      type: object
      properties:
        created:
          type: integer
          description: 创建时间戳
        data:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                description: 图片 URL（response_format=url 时）
              b64_json:
                type: string
                description: Base64 编码的图片（response_format=b64_json 时）
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'OpenAI 风格认证（Authorization: Bearer <token>）'

````