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

# 上传图片

> 上传参考图并获取可用于图像生成的图片地址。

使用项目的 API 密钥上传 PNG、JPEG 或 WebP 图片。可以上传本地文件，也可以提供可公开访问的图片地址。

上传本地文件（`@` 后是运行 curl 的机器上的文件路径）：

```bash theme={null}
curl -X POST 'https://ai.xbrod.com/v1/uploads/images' \
  -H 'Authorization: Bearer <本项目 API 密钥>' \
  -F 'file=@reference.png'
```

通过图片地址上传：

```bash theme={null}
curl -X POST 'https://ai.xbrod.com/v1/uploads/images' \
  -H 'Authorization: Bearer <本项目 API 密钥>' \
  -H 'Content-Type: application/json' \
  -d '{"image_url":"https://example.com/reference.png"}'
```

成功时返回上传后的公网图片地址，以及文件大小和类型：

```json theme={null}
{
  "url": "https://images-1234567890.cos.ap-shanghai.myqcloud.com/images/9a9b3d4d29ca4b68da9e001519f4d780.png",
  "bytes": 53646,
  "content_type": "image/png",
  "filename": "upload.png",
  "created_at": 1792061639
}
```

将返回的 `url` 作为后续图片生成请求的 `image_urls` 项传入；上传与生成是两次独立请求。

本地文件及 URL 指向的图片输入最大为 64 MiB。20 MiB 以内原样上传；超过 20 MiB 时，网关不缩小图片尺寸：PNG 优先尝试无损压缩；不透明的 PNG 若无损压缩后仍超过限制，再尝试转为高画质 JPEG，返回地址、`filename` 和 `content_type` 将相应变为 JPEG；有透明度的 PNG 不会转为 JPEG。JPEG 会尝试优先使用较高画质重新编码。上传后的图片最大为 20 MiB（20,971,520 字节）。超过 64 MiB、图片过大无法安全解码，或压缩后仍超过 20 MiB 时返回 413；超过 20 MiB 的 WebP 暂不支持压缩，也返回 413。重新编码可能改变部分非图像元数据；需要保留原文件时请先自行压缩后再上传。


## OpenAPI

````yaml openapi.yaml POST /v1/uploads/images
openapi: 3.0.3
info:
  title: new-api public API (documentation preview)
  version: 0.1.0
  description: >-
    Gateway-facing contracts for the first set of documented models. The enabled
    models and billing depend on each deployment's settings.
servers:
  - url: https://ai.xbrod.com
    description: 本项目线上 API 地址
security:
  - bearerAuth: []
paths:
  /v1/uploads/images:
    post:
      summary: 上传图片
      description: 上传本地图片文件或提供图片地址，返回可供图片生成接口使用的 URL。
      operationId: uploadImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    PNG、JPEG 或 WebP 图片，输入最多 64 MiB；超过 20 MiB 时不缩小尺寸，尝试压缩。不透明的
                    PNG 如无损压缩后仍超限，可能转为 JPEG。输出最多 20 MiB。
          application/json:
            schema:
              type: object
              required:
                - image_url
              additionalProperties: false
              properties:
                image_url:
                  type: string
                  format: uri
                  description: 可公开访问的 HTTP/HTTPS 图片地址；输入最多 64 MiB，输出最多 20 MiB。
            example:
              image_url: https://example.com/reference.png
      responses:
        '200':
          description: 图片上传成功。
          content:
            application/json:
              schema:
                type: object
                required:
                  - url
                  - bytes
                  - content_type
                properties:
                  url:
                    type: string
                    format: uri
                    description: 可直接用于图片生成请求 image_urls 的公网地址。
                  bytes:
                    type: integer
                    format: int64
                  content_type:
                    type: string
                    description: 实际上传图片的类型；PNG 转换后为 image/jpeg。
                  filename:
                    type: string
                    description: 实际上传图片的文件名；PNG 转换后后缀为 .jpg。
                  created_at:
                    type: integer
                    format: int64
              example:
                url: >-
                  https://images-1234567890.cos.ap-shanghai.myqcloud.com/images/9a9b3d4d29ca4b68da9e001519f4d780.png
                bytes: 53646
                content_type: image/png
                filename: upload.png
                created_at: 1792061639
        '400':
          description: 缺少 file 或 image_url、请求格式有误，或图片地址不安全。
        '401':
          description: API 密钥无效。
        '413':
          description: 输入图片超过 64 MiB，无法在保留尺寸的前提下压缩到 20 MiB，或超限图片格式暂不支持压缩。
        '415':
          description: 图片类型不受支持。
        '429':
          description: 上传频率过高。
        '502':
          description: 图片地址无法读取，或上传服务返回错误。
        '503':
          description: 上传服务暂不可用。
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key created in this gateway, not a provider key.

````

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