文件上传

接口标识: fileupload 价格: 0

接口介绍
接口文档
在线测试

接口简介

将文件上传至独立云存储空间，获取公网可访问的文件URL地址，支持图像、文档、音频、视频等多种格式。

详细介绍

## 产品介绍

文件上传API提供安全高效的文件上传能力，支持图像、文档、音频、视频四大类文件格式，上传后返回公网可访问的URL地址。

## 功能特点

- 支持多种文件格式：图像（jpg/png/gif/webp等）、文档（pdf/doc/xlsx/txt等）、音频（mp3/wav/flac等）、视频（mp4/avi/mov等）
- 按文件类型分别设置大小上限与每日上传次数限制
- 云存储，返回永久可访问的公网URL
- 标准签名鉴权，保障接口调用安全

## 支持的文件类型

| 类别 | 支持的扩展名 |
|------|-------------|
| 图像 | jpg, jpeg, png, gif, bmp, webp, tiff |
| 文档 | pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv |
| 音频 | mp3, wav, aac, ogg, flac, m4a |
| 视频 | mp4, avi, mov, mkv, webm, flv |

## 接口调用地址

```
POST /api/v1/fileupload
```

请求方式为 `multipart/form-data`，文件字段名为 `file`。

## 公共请求参数

所有接口调用均需携带以下公共参数（与业务参数一同提交）：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pid | string | 是 | 用户ID（登录用户中心可见） |
| sign | string | 是 | 签名值（签名算法见下方说明） |

## PHP 完整调用示例

以下是一个完整的 PHP 文件上传示例，包含签名生成、文件上传、响应处理全流程：

```php
<?php
/**
 * 文件上传接口 - PHP 调用示例
 *
 * 使用前请修改下方三项配置：
 *   $host      接口域名（默认即本平台域名）
 *   $pid       用户ID（登录用户中心可见）
 *   $appSecret API密钥（用户中心 - API设置 生成）
 *
 * 环境要求：PHP 5.6+，需开启 curl 扩展
 */

// ================= 配置区 =================
$host      = 'https://api.phpwc.com';  // 接口域名
$pid       = 'YOUR_PID';               // 用户ID
$appSecret = 'YOUR_APP_SECRET';        // API密钥
// =========================================

/**
 * 生成签名
 * 规则：排除sign与空值 → key升序 → k=v&拼接 → 尾接密钥 → MD5
 *
 * @param array  $params 全部请求参数（不含sign）
 * @param string $secret API密钥
 * @return string 32位小写十六进制签名
 */
function makeSign($params, $secret)
{
    unset($params['sign']);
    ksort($params);
    $str = '';
    foreach ($params as $k => $v) {
        if ($v === '' || $v === null) {
            continue;
        }
        $str .= ($str ? '&' : '') . $k . '=' . $v;
    }
    $str .= $secret;
    return md5($str);
}

/**
 * 上传文件到接口
 *
 * @param string $filePath 本地文件路径
 * @return array 接口返回结果
 */
function uploadFile($filePath)
{
    global $host, $pid, $appSecret;

if (!file_exists($filePath)) {
        throw new Exception('文件不存在: ' . $filePath);
    }

// 1. 组装公共参数
    $params = [
        'pid' => $pid,
    ];

// 2. 生成签名
    $params['sign'] = makeSign($params, $appSecret);

// 3. 构造 multipart/form-data 请求
    $postData = [
        [
            'name'     => 'file',
            'contents' => fopen($filePath, 'r'),
            'filename' => basename($filePath),
        ],
    ];

// 将公共参数追加到 postData
    foreach ($params as $key => $value) {
        $postData[] = [
            'name'     => $key,
            'contents' => $value,
        ];
    }

// 4. 使用 cURL 发送请求
    $url = rtrim($host, '/') . '/api/v1/fileupload';
    $ch  = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 60);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

$response   = curl_exec($ch);
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $error      = curl_error($ch);
    curl_close($ch);

if ($error) {
        throw new Exception('cURL错误: ' . $error);
    }

$result = json_decode($response, true);
    if (!$result) {
        throw new Exception('响应解析失败，HTTP状态: ' . $statusCode);
    }

return $result;
}

// ================= 调用示例 =================
try {
    // 替换为实际要上传的文件路径
    $file = 'example.jpg';

$result = uploadFile($file);

// 判断返回状态
    if ($result['code'] === 0) {
        echo "上传成功！\n";
        echo "文件URL: " . $result['data']['file_url'] . "\n";
        echo "文件大小: " . $result['data']['file_size'] . " 字节\n";
        echo "文件类型: " . $result['data']['file_type'] . "\n";
        echo "存储名称: " . $result['data']['file_name'] . "\n";
    } else {
        echo "上传失败：[" . $result['code'] . "] " . $result['desc'] . "\n";
    }
} catch (Exception $e) {
    echo "异常：" . $e->getMessage() . "\n";
}
```

## 签名算法

所有API调用均需携带签名参数，签名采用 MD5 算法，步骤如下：

**步骤一**：取全部请求参数（业务参数 + pid），去除 `sign` 本身与值为空的参数；

**步骤二**：按参数名（key）ASCII 升序排列（ksort）；

**步骤三**：按 `key=value` 格式用 `&` 连接，如：`icp=phpwc.com&pid=1`；

**步骤四**：在字符串末尾直接拼接 API 密钥（不加任何连接符）；

**步骤五**：对最终字符串做 MD5，得到 32 位小写十六进制签名值。

## 返回字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| file_url | string | 文件的公网访问URL地址 |
| file_size | integer | 文件大小（字节） |
| file_type | string | 文件MIME类型 |
| file_name | string | 存储文件名 |

## 成功响应示例

```json
{
    "code": 0,
    "desc": "成功",
    "data": {
        "file_url": "http://apifujian.phpwc.net/apifile/20260906/1757145600_a1b2c3.jpg",
        "file_size": 102400,
        "file_type": "image/jpeg",
        "file_name": "1757145600_a1b2c3.jpg"
    }
}
```

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 40101 | 缺少必要参数（pid/sign） |
| 40102 | 签名验证失败 |
| 40301 | 不支持的文件类型 |
| 40302 | 文件大小超过限制 |
| 40303 | 今日上传次数已达上限 |
| 50000 | 服务器内部错误 |

接口地址： https://www.phpwc.cn/api/fileupload

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`file`	string	选填	-	上传的文件（multipart/form-data，网关转为 file_base64）
`reset`	int	选填	`0`	去重控制：0=相同文件不重复上传（默认），1=强制重新上传

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`file_id`	string	文件唯一标识（22位），可用于其他接口的 file_id 参数引用已上传文件
`oss_status`	string	上传状态：processing=上传中，finish=已完成，fail=失败
`file_size`	int	文件大小（KB）
`file_type`	string	文件MIME类型
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

请先登录后使用在线测试