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

# 文件上传

> 通过 multipart 表单上传单个文件。

**路径：** `POST https://api.omniall.ai/v1/files`

可将返回的 `url` 用于其它接口的图片 / 视频 / 音频参考。

鉴权：`Authorization: Bearer sk-...`



## OpenAPI

````yaml zh-CN/openapi/files-upload.yaml POST /v1/files
openapi: 3.1.0
info:
  title: Omniall AI — 文件上传
  version: 1.0.0
  description: |-
    上传文件到 Omniall 存储，返回可公网访问的 CDN URL。

    **路径：** `POST https://api.omniall.ai/v1/files`

    Content-Type：`multipart/form-data`。字段名：`file`。

    文件大小限制常见为 **10MB**（站点管理员可配置）。

    鉴权：`Authorization: Bearer sk-...`
servers:
  - url: https://api.omniall.ai
security: []
paths:
  /v1/files:
    post:
      tags:
        - 平台
      summary: 文件上传
      description: |-
        通过 multipart 表单上传单个文件。

        **路径：** `POST https://api.omniall.ai/v1/files`

        可将返回的 `url` 用于其它接口的图片 / 视频 / 音频参考。

        鉴权：`Authorization: Bearer sk-...`
      operationId: uploadFile
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            example: Bearer sk-...
          description: Bearer API Key。
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: 要上传的文件（必填）。大小限制常见为 10MB。
            encoding:
              file:
                contentType: application/octet-stream
      responses:
        '200':
          description: 上传成功
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - object
                  - url
                  - filename
                  - bytes
                  - created_at
                properties:
                  id:
                    type: string
                    description: 文件 ID，如 `file-xxxxxxxx`。
                    example: file-xxxxxxxx
                  object:
                    type: string
                    example: file
                  url:
                    type: string
                    description: 上传后的公网 CDN URL。
                    example: https://cdn.example.com/files/uploads/2026/06/03/xxx.pdf
                  filename:
                    type: string
                    description: 原始文件名。
                    example: demo.pdf
                  bytes:
                    type: integer
                    description: 文件大小（字节）。
                    example: 12345
                  created_at:
                    type: integer
                    description: Unix 时间戳（秒）。
                    example: 1710000000
              example:
                id: file-xxxxxxxx
                object: file
                url: https://cdn.example.com/files/uploads/2026/06/03/xxx.pdf
                filename: demo.pdf
                bytes: 12345
                created_at: 1710000000
        '400':
          description: 请求无效（缺少 file、空文件、类型不允许等）
        '413':
          description: 文件过大
        '503':
          description: 文件存储未配置

````

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