# 用户文件上传 API Documentation

> 将文件上传到当前 API Key 对应用户的专属空间。需实名认证。免费额度默认 100MB；超出部分按每 10MB = 1 算力在上传时扣费。

## Overview

This document describes how to call the **用户文件上传** API.

- **Model / path slug**: `file/upload`
- **Task type**: `sync` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/49`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `POST https://xiaoapis.com/api/file/upload`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `POST`

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `file` | Yes | 上传文件（multipart 字段名 file，兼容 upload/media） |
| `folder` | No | 可选子目录 |
| `name` | No | 可选自定义文件名（不含扩展名） |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
curl -X POST "https://xiaoapis.com/api/file/upload?key=你的密钥" -F "file=@/path/to/demo.mp4"
```

## Details

## 接口说明：

文件与当前密钥用户绑定。免费额度默认 **100MB**；超出部分按 **每 10MB = 1 算力**（向上取整），仅对本次上传落入超额的字节计费。算力不足则拒绝上传。

关联：[配额查询](/doc/50)、[文件列表](/doc/51)、[删除文件](/doc/52)

## 计费示例：

已用 495MB，再传 20MB → 超额约 15MB → 扣 2 算力。

## Response Example

```json
{
    "code": 200,
    "msg": "上传成功",
    "data": {
        "file_id": 1,
        "url": "https://xiaoapis.com/upload/user/1/2026/09/20/demo.mp4",
        "path": "/upload/user/1/2026/09/20/demo.mp4",
        "size": 1048576,
        "storage_quota": 524288000,
        "storage_used": 1048576,
        "storage_remain": 523239424
    }
}
```

## Error Codes

| 状态码 | 说明 |
| --- | --- |
| 200 | 上传成功 |
| 400 | 参数错误或配额不足 |
| 401/403 | 密钥无效 |

## Usage Flow

1. Obtain your API Key from the console
2. Call the endpoint with `key` and required parameters
3. Parse the JSON (or binary) response according to the examples above

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._