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

# Upload File from URL

`POST /api/common/upload/url`

Upload files by providing a remote URL. The file will be downloaded from the URL and stored in PoYo AI storage.

## Request body

- UploadUrlRequest
  - `file_url` string, uri, required — The remote file URL to upload. Must be a publicly accessible URL using HTTP or HTTPS protocol. **Supported formats**: JPEG, PNG, GIF, WebP **Note**: The file will be downloaded from this URL and stored in PoYo AI storage.
  - `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 URL, unsupported file type, or download failure
- `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)