文件上传接口接入指南

概述

本文档介绍如何通过 API 使用 SiliEvo 平台的文件上传服务，支持上传图片、音频、视频等文件到阿里云 OSS，获取临时签名 URL，用于后续的多模态模型调用（如语音合成音色创建、视频生成、图生图等）。

前提条件

请牢记 SiliEvo 中转服务的核心两要素：

中转基地址 (Base URL): https://api.numspirit.com/

安全秘钥 (API Key / Token): 通过平台官网 https://numspirit.com 或联系 15685255305 申请，形如 sk-silievo-xxxxxxxx

接口说明

请求 Header

Content-Type: multipart/form-data
Authorization: Bearer sk-silievo-xxxxxxxx

第一部分：单文件上传

接口信息

属性	说明
接口地址	`POST https://api.numspirit.com/v1/uploads`
请求方式	`multipart/form-data`
支持文件	图片、音频、视频

请求参数

参数	类型	必填	说明
`file`	file	是	要上传的文件

支持的文件类型

类型	MIME 类型
图片	`image/png`, `image/jpeg`, `image/jpg`, `image/webp`, `image/gif`
音频	`audio/mpeg`, `audio/wav`, `audio/mp3`, `audio/aac`, `audio/ogg`, `audio/flac`, `audio/x-wav`, `audio/x-m4a`
视频	`video/mp4`, `video/webm`, `video/quicktime`

响应示例

{
    "success": true,
    "data": {
        "url": "https://silievo-oss.oss-cn-beijing.aliyuncs.com/relay/123/upload/xxx.jpg?Expires=1783246243&OSSAccessKeyId=...&Signature=...",
        "oss_key": "relay/123/upload/xxx.jpg",
        "mime": "image/jpeg",
        "size": 1024000
    }
}

响应字段说明：

字段	类型	说明
`success`	boolean	上传是否成功
`data.url`	string	文件的临时签名 URL，可直接访问
`data.oss_key`	string	文件在 OSS 上的存储路径
`data.mime`	string	文件的 MIME 类型
`data.size`	integer	文件大小（字节）

cURL 示例

第二部分：批量文件上传

接口信息

属性	说明
接口地址	`POST https://api.numspirit.com/v1/uploads/batch`
请求方式	`multipart/form-data`
限制	单次最多上传 5 个文件

请求参数

参数	类型	必填	说明
`files`	file[]	是	要上传的文件列表，最多 5 个

响应示例

{
    "success": true,
    "data": [
        {
            "url": "https://silievo-oss.oss-cn-beijing.aliyuncs.com/relay/123/upload/image1.jpg?...",
            "oss_key": "relay/123/upload/image1.jpg",
            "mime": "image/jpeg",
            "size": 1024000
        },
        {
            "url": "https://silievo-oss.oss-cn-beijing.aliyuncs.com/relay/123/upload/image2.png?...",
            "oss_key": "relay/123/upload/image2.png",
            "mime": "image/png",
            "size": 2048000
        }
    ]
}

cURL 示例

第三部分：完整代码示例

Python

Node.js / TypeScript

Java

第四部分：应用场景

常见用途

语音合成音色创建 - 上传 WAV 音频样本，获取 URL 后用于创建自定义音色

视频生成 - 上传参考图片或视频，用于图生视频、多图参考生视频

多模态对话 - 上传图片，用于视觉理解、图文对话

文件存储 - 临时存储文件，获取可访问的签名 URL

完整工作流示例：音色创建

附录：错误码速查表

错误类型	HTTP 状态码	说明	解决方案
`auth_error`	401	认证失败，API Key 无效或未提供	检查 Authorization Header 格式
`invalid_request`	400	请求参数错误	检查文件是否为空或格式是否正确
`unsupported_file_type`	400	不支持的文件类型	检查文件 MIME 类型是否在支持列表中
`quota_exceeded`	402	额度已用尽	充值或联系客服
`internal_error`	500	服务器内部错误	稍后重试或联系客服

注意事项

文件大小限制：单文件大小建议不超过 100MB

签名 URL 有效期：返回的 URL 为临时签名 URL，有过期时间，请及时使用

文件类型校验：上传的文件会被校验 MIME 类型，不支持的类型将被拒绝

批量上传限制：单次批量上传最多支持 5 个文件

并发限制：每个 Token 有速率限制，请参考 API 文档

技术支持: 如有任何问题，请联系客服微信或加入服务群获取帮助。

文件上传接口

文件上传接口接入指南#

概述#

前提条件#

接口说明#

请求 Header#

第一部分：单文件上传#

接口信息#

请求参数#

支持的文件类型#

响应示例#

cURL 示例#

第二部分：批量文件上传#

接口信息#

请求参数#

响应示例#

cURL 示例#

第三部分：完整代码示例#

Python#

Node.js / TypeScript#

Java#

第四部分：应用场景#

常见用途#

完整工作流示例：音色创建#

附录：错误码速查表#

注意事项#

文件上传接口接入指南

概述

前提条件

接口说明

请求 Header

第一部分：单文件上传

接口信息

请求参数

支持的文件类型

响应示例

cURL 示例

第二部分：批量文件上传

接口信息

请求参数

响应示例

cURL 示例

第三部分：完整代码示例

Python

Node.js / TypeScript

Java

第四部分：应用场景

常见用途

完整工作流示例：音色创建

附录：错误码速查表

注意事项