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

# File Upload (URL)

> Download a file from a remote URL and upload it to storage.

Download files from remote URLs and upload to cloud storage.

**Key Features:**

* **Remote Download** - Download files from any public URL and store them
* **Custom Filename** - Optionally specify the saved filename
* **Large File Support** - Supports files up to 50MB
* **Dual Access** - Returns both global and China access URLs


## OpenAPI

````yaml /en/files-openapi.json POST /api/upload/url
openapi: 3.0.3
info:
  title: File Upload API
  description: >-
    Upload files via Base64, multipart/form-data, or remote URL. Powered by
    Cloudflare R2.
  version: 1.0.0
  contact:
    name: SinanCode
    url: https://sinancode.com
servers:
  - url: https://files-api.sinancode.com
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Upload
    description: File upload operations
paths:
  /api/upload/url:
    post:
      tags:
        - Upload
      summary: Upload file from remote URL
      description: Download a file from a remote URL and upload it to storage.
      operationId: uploadUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UrlUploadRequest'
            example:
              url: https://example.com/image.png
      responses:
        '201':
          $ref: '#/components/responses/UploadSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    UrlUploadRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: The remote URL of the file to download and upload
          example: https://example.com/image.png
        filename:
          type: string
          description: Optional custom filename (with extension)
          example: my-image.png
    UploadSuccessResponse:
      type: object
      required:
        - url
        - cn_url
        - key
        - md5
        - size
        - content_type
        - expires_at
      properties:
        url:
          type: string
          format: uri
          description: Public URL to access the uploaded file (global)
          example: https://upload-tmp.sinancode.com/uploads/user123/abc123def456.png
        cn_url:
          type: string
          format: uri
          description: Public URL to access the uploaded file (China)
          example: >-
            https://beijing-user-upload-tmp.tos-cn-beijing.volces.com/uploads/user123/abc123def456.png
        key:
          type: string
          description: Storage key of the uploaded file
          example: uploads/user123/abc123def456.png
        md5:
          type: string
          description: Hash of the file content (SHA-256 truncated)
          example: d41d8cd98f00b204e9800998ecf8427e
        size:
          type: integer
          description: File size in bytes
          example: 12345
        content_type:
          type: string
          description: MIME type of the file
          example: image/png
        expires_at:
          type: string
          format: date-time
          description: Expiration time of the file (ISO 8601)
          example: '2024-01-17T00:00:00.000Z'
    ErrorResponse:
      type: object
      required:
        - message
        - error_code
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Invalid file format
        error_code:
          type: string
          description: Machine-readable error code
          example: UPLOAD.INVALID_FILE
  responses:
    UploadSuccess:
      description: File uploaded successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UploadSuccessResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: 'Missing required field: data'
            error_code: UPLOAD.INVALID_FILE
    Unauthorized:
      description: Missing or invalid authorization token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Missing authorization token
            error_code: AUTH.MISSING_TOKEN
    PayloadTooLarge:
      description: File size exceeds the maximum limit (50MB)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: File size exceeds maximum limit of 50MB
            error_code: UPLOAD.FILE_TOO_LARGE
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Internal server error
            error_code: INTERNAL_ERROR
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Authorization token obtained from api.sinancode.com

````