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

# 通过 URL 上传文件

> 提供远程 URL，将文件上传到 PoYo AI

## 使用指南

* 该接口通过提供远程 URL 将文件上传到 PoYo AI
* 系统会自动从指定 URL 下载文件，并存储到 PoYo AI 存储中
* 适合从外部服务器迁移文件，或对接第三方文件来源
* 返回文件的直接访问 URL，文件保留 72 小时

## 参数详情

* **文件 URL 要求**：

  * `file_url` 必须是使用 HTTP 或 HTTPS 协议的公开可访问 URL

  * 远程服务器必须允许无需认证即可下载该文件

  * 支持的文件格式：仅 **JPEG、PNG、GIF、WebP**

  * 上传数量上限：**每次请求 1 张图片**

* **存储配置**：

  * 所有文件在存储路径中都会自动加上 `temp/` 前缀

  * 如果指定 `upload_path: "avatars"`，实际路径为 `temp/avatars`

  * 文件在上传 **72 小时**后过期并自动删除

* **文件命名**：

  * 如果未提供 `file_name`，系统会按以下格式生成唯一文件名：`{timestamp}_{random}_{extension}`

  * 自动生成的文件名示例：`20251229130857_a8B9cD2e.png`

## 开发者说明

* 确保源 URL 公开可访问，且不需要认证或特殊请求头

* 下载过程可能需要几秒钟，取决于文件大小和网络状况

* 如需持久保存，请在 72 小时过期前将文件下载到本地

* 响应中的 `file_url` 和 `download_url` 完全相同，都可以直接访问已上传的文件

## 速率限制与配额

* **速率限制**：每个已认证用户、每个上传接口，在 60 秒固定窗口内最多 10 次请求

* 超出速率限制时，会收到 `429 Too Many Requests` 错误

* 固定窗口从窗口内第一次请求开始计算，同一用户的 JWT 请求和 API Key 请求共享该窗口

* 使用指数退避重试逻辑处理速率限制错误

## 常见错误场景

* **URL 无效**：提供的 URL 格式错误或无法访问

* **下载失败**：从远程 URL 下载时出现网络超时或连接问题

* **不支持的文件类型**：URL 指向的文件不是支持的图片格式（JPEG、PNG、GIF、WebP）

* **认证错误**：Authorization 请求头中的 API Key 缺失或无效


## OpenAPI

````yaml zh/api-manual/file-series/upload-url.json POST /api/common/upload/url
openapi: 3.0.0
info:
  title: PoYo AI - 通过 URL 上传文件
  description: 提供远程 URL 即可将文件上传到 PoYo AI。系统会自动从指定位置下载并存储文件。
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: 生产环境
security:
  - BearerAuth: []
paths:
  /api/common/upload/url:
    post:
      tags:
        - File Upload
      summary: 通过 URL 上传文件
      description: 提供远程 URL 上传文件。系统会从该 URL 下载文件并存储到 PoYo AI 存储中。
      operationId: uploadFileFromUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadUrlRequest'
            examples:
              basic-upload:
                summary: 基础 URL 上传
                value:
                  file_url: https://example.com/images/sample.jpg
              custom-naming:
                summary: 使用自定义文件名上传
                value:
                  file_url: https://example.com/images/photo.png
                  file_name: my-custom-image.png
              custom-path:
                summary: 使用自定义路径和文件名上传
                value:
                  file_url: https://example.com/images/avatar.webp
                  upload_path: avatars
                  file_name: user-avatar.webp
      responses:
        '200':
          description: 文件上传成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
        '400':
          description: 请求错误 - URL 无效、文件类型不支持或下载失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid-url:
                  summary: 文件 URL 无效
                  value:
                    detail: >-
                      Failed to download file:
                      HTTPSConnectionPool(host='invalid-url.com', port=443): Max
                      retries exceeded
                unsupported-type:
                  summary: 文件类型不支持
                  value:
                    detail: 'Unsupported file type: application/pdf'
                download-failed:
                  summary: 下载失败
                  value:
                    detail: 'Failed to download file: Connection timeout'
        '401':
          description: 未授权 - 缺少认证信息或认证无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not-authenticated:
                  summary: 未认证
                  value:
                    detail: Not authenticated
        '429':
          description: 超出速率限制 - 每个已认证用户在每个上传接口上，每 60 秒固定窗口内最多 10 次请求
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate-limit:
                  summary: 超出速率限制
                  value:
                    detail: Rate limit exceeded
        '500':
          description: 服务器错误 - 存储连接或上传失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                server-error:
                  summary: 服务器错误
                  value:
                    detail: 'Upload failed: Unable to connect to R2 storage'
components:
  schemas:
    UploadUrlRequest:
      type: object
      required:
        - file_url
      properties:
        file_url:
          type: string
          format: uri
          description: |-
            要上传的远程文件 URL。

            必须是使用 HTTP 或 HTTPS 协议、可公开访问的 URL。

            **支持的格式**：JPEG、PNG、GIF、WebP

            **注意**：系统会从该 URL 下载文件并存储到 PoYo AI 存储中。
          example: https://example.com/images/sample.jpg
        upload_path:
          type: string
          description: |-
            自定义存储目录路径。

            未指定时，系统会自动对文件分类。

            **注意**：无论指定什么路径，所有文件都会以 `temp/` 前缀存储。
          example: avatars
        file_name:
          type: string
          description: |-
            上传文件的自定义文件名。

            未指定时，系统会按以下格式生成唯一文件名：`{timestamp}_{random}_{extension}`

            **自动生成的文件名示例**：`20251229130857_a8B9cD2e.png`
          example: my-custom-image.png
    UploadResponse:
      type: object
      required:
        - success
        - code
        - msg
        - data
      properties:
        success:
          type: boolean
          example: true
          description: 上传是否成功
        code:
          type: integer
          example: 200
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
        msg:
          type: string
          example: File uploaded successfully
          description: 响应消息
        data:
          type: object
          required:
            - file_id
            - file_name
            - original_name
            - file_size
            - mime_type
            - upload_path
            - file_url
            - download_url
            - upload_time
            - expires_at
          properties:
            file_id:
              type: string
              example: 1bdfdbac6ebc2228d0b398d728bf4699
              description: 文件唯一标识（MD5 哈希）
            file_name:
              type: string
              example: test-image.png
              description: 存储后的文件名
            original_name:
              type: string
              example: image-from-url.png
              description: URL 中的原始文件名
            file_size:
              type: integer
              example: 1419815
              description: 文件大小（字节）
            mime_type:
              type: string
              example: image/png
              description: 上传文件的 MIME 类型
            upload_path:
              type: string
              example: temp/test-uploads
              description: 存储路径（包含 temp/ 前缀）
            file_url:
              type: string
              format: uri
              example: https://storage.poyo.ai/temp/test-uploads/test-image.png
              description: 上传文件的直接访问 URL
            download_url:
              type: string
              format: uri
              example: https://storage.poyo.ai/temp/test-uploads/test-image.png
              description: 下载 URL（与 file_url 相同）
            upload_time:
              type: string
              format: date-time
              example: '2025-12-29T13:08:57.673515'
              description: 上传时间戳，ISO 8601 格式
            expires_at:
              type: string
              format: date-time
              example: '2026-01-01T13:08:57.673515'
              description: 过期时间戳，ISO 8601 格式（上传后 72 小时）
    ErrorResponse:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: 描述错误原因的错误信息
          example: Not authenticated
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证。


        创建 API Key：登录 PoYo，进入 **仪表盘 → API
        密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建
        Key。


        在请求头中添加：


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

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