---
title: "Upload File from Base64"
method: POST
path: "/api/common/upload/base64"
tags: ["File Upload"]
---

# Upload File from Base64

`POST /api/common/upload/base64`

Upload files using Base64-encoded data or Data URL format. Supports both pure Base64 strings and Data URL format with MIME type prefix.

## Request body

- UploadBase64Request
  - `base64_data` string, required — Base64-encoded file data. Supports two formats: 1. **Data URL format**: `data:image/png;base64,iVBORw0KGgo...` 2. **Pure Base64 string**: `iVBORw0KGgo...` (without MIME type prefix) **Supported formats**: JPEG, PNG, GIF, WebP **Note**: The Base64 string should not include any whitespace or newline characters.
  - `upload_path` string — Custom storage directory path. If not specified, the system will auto-categorize the file. **Note**: All files are stored with a `temp/` prefix regardless of the specified path.
  - `file_name` string — Custom filename for the uploaded file. If not specified, the system will generate a unique filename in the format: `{timestamp}_{random}_{extension}` **Example auto-generated name**: `20251229130857_a8B9cD2e.png`

## Response `200`

File uploaded successfully

- UploadResponse
  - `success` boolean, required — Indicates whether the upload was successful
  - `code` integer, required — HTTP status code
  - `msg` string, required — Response message
  - `data` object, required
    - `file_id` string, required — Unique file identifier (MD5 hash)
    - `file_name` string, required — The stored filename
    - `original_name` string, required — The original filename from the URL
    - `file_size` integer, required — File size in bytes
    - `mime_type` string, required — MIME type of the uploaded file
    - `upload_path` string, required — Storage path (includes temp/ prefix)
    - `file_url` string, uri, required — Direct access URL for the uploaded file
    - `download_url` string, uri, required — Download URL (same as file_url)
    - `upload_time` string, date-time, required — Upload timestamp in ISO 8601 format
    - `expires_at` string, date-time, required — Expiration timestamp in ISO 8601 format (72 hours after upload)

## Other responses

- `400` — Bad request - Invalid Base64, unsupported file type, or invalid data
- `401` — Unauthorized - Missing or invalid authentication
- `429` — Rate limit exceeded - 10 requests per 60-second fixed window per authenticated user, per upload endpoint
- `500` — Server error - Storage connection or upload failure

---

[API](https://skmtc.net/poyo/apis/poyo-ai-hunyuan-3d-v3-1-api.md) · [All operations](https://skmtc.net/poyo/apis/poyo-ai-hunyuan-3d-v3-1-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/poyo/poyo-ai-hunyuan-3d-v3-1-api/revisions/4b46904b78eb/schema)