API 文档
多媒体处理平台 RESTful API 接口文档
概述
多媒体处理平台提供 RESTful API 接口,允许开发者通过 API 调用使用平台的所有核心功能。API 支持 JSON 格式的请求和响应。
https://www.johngko.com所有 API 请求需要在 Header 中携带 API 密钥(Bearer Token):
Authorization: Bearer YOUR_API_KEY- 请求格式: application/json
- 响应格式: application/json
- 文件上传: multipart/form-data
快速开始
使用 POST /api/v1/upload 接口上传待处理的文件,获取 file_id。
curl -X POST "https://www.johngko.com/api/v1/upload" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@video.mp4"
使用 POST /api/v1/tasks 接口创建处理任务。
curl -X POST "https://www.johngko.com/api/v1/tasks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"file_id": 123, "function_code": "video_compress", "parameters": {"quality": "medium"}}'轮询 GET /api/v1/tasks/:id 接口查询任务状态,完成后下载结果。
curl -X GET "https://www.johngko.com/api/v1/tasks/456" \ -H "Authorization: Bearer YOUR_API_KEY"
认证
API 使用 Bearer Token 认证方式。所有请求必须在 Header 中携带有效的 API 密钥。
| Authorization | Bearer YOUR_API_KEY | 必填,API 密钥 |
| Content-Type | application/json | POST/PUT 请求必填 |
| 状态码 | 错误信息 | 说明 |
|---|---|---|
401 | 缺少认证信息 | 未提供 Authorization 头 |
401 | 无效的 API 密钥 | 密钥格式错误或不存在 |
401 | API 密钥已被撤销 | 密钥已被用户撤销 |
403 | 无 API 使用权限 | 账户未开通 API 权限 |
API 端点
/api/v1/functions获取功能列表获取所有可用的处理功能列表及其参数定义。
| 字段 | 类型 | 说明 |
|---|---|---|
success | boolean | 请求是否成功 |
data.functions | array | 功能列表 |
data.total | number | 功能总数 |
data.is_vip | boolean | 是否为 VIP 用户 |
{
"success": true,
"data": {
"functions": [
{
"code": "video_compress",
"name": "视频压缩",
"category": "VIDEO",
"description": "通过调节质量参数压缩视频体积",
"available": true
}
],
"total": 53,
"is_vip": true
}
}/api/v1/upload上传文件上传待处理的文件,支持视频、音频、图像、文档等格式。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | File | 是 | 要上传的文件 |
| 字段 | 类型 | 说明 |
|---|---|---|
data.file_id | number | 文件ID,用于后续任务创建 |
data.file_type | string | 文件类型: VIDEO, AUDIO, IMAGE, DOCUMENT |
data.filename | string | 原始文件名 |
data.file_size | number | 文件大小(字节) |
{
"success": true,
"data": {
"file_id": 123,
"file_type": "VIDEO",
"filename": "example.mp4",
"file_size": 10485760,
"mime_type": "video/mp4"
}
}/api/v1/tasks创建处理任务创建文件处理任务,任务将进入队列异步处理。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file_id | number | 是 | 上传文件返回的文件ID |
function_code | string | 是 | 功能代码,如 video_compress |
parameters | object | 否 | 处理参数,详见功能参数参考 |
| 字段 | 类型 | 说明 |
|---|---|---|
data.task_id | number | 任务ID,用于查询状态 |
data.task_no | string | 任务编号 |
data.status | string | 任务状态: QUEUED, PROCESSING, COMPLETED, FAILED |
data.concurrent_info | object | 并发信息 |
{
"success": true,
"data": {
"task_id": 456,
"task_no": "TASKMLXV5D7U1F4E0A31",
"status": "QUEUED",
"function_code": "video_compress",
"function_name": "视频压缩",
"input_filename": "example.mp4",
"created_at": "2024-01-01T00:00:00.000Z",
"concurrent_info": {
"limit": 3,
"current": 1,
"available": 2
}
}
}/api/v1/tasks/:id查询任务状态查询指定任务的详细信息和处理状态。
| 参数 | 类型 | 说明 |
|---|---|---|
id | number | 任务ID |
| 状态 | 说明 |
|---|---|
QUEUED | 任务已入队,等待处理 |
PROCESSING | 任务正在处理中 |
COMPLETED | 任务处理完成,可下载结果 |
FAILED | 任务处理失败 |
{
"success": true,
"data": {
"task_id": 456,
"task_no": "TASKMLXV5D7U1F4E0A31",
"function_code": "video_compress",
"function_name": "视频压缩",
"status": "COMPLETED",
"progress": 100,
"input_filename": "example.mp4",
"input_filesize": 10485760,
"output_filename": "example_compressed.mp4",
"output_filesize": 5242880,
"error_message": null,
"created_at": "2024-01-01T00:00:00.000Z",
"started_at": "2024-01-01T00:00:01.000Z",
"completed_at": "2024-01-01T00:00:30.000Z",
"download_url": "${baseUrl}/api/v1/tasks/456/download"
}
}/api/v1/tasks/:id/download下载处理结果下载处理完成的文件。仅当任务状态为 COMPLETED 时可用。
成功时返回文件流(Content-Type 根据文件类型设置),失败时返回 JSON 错误信息。
- 下载链接需要在 Header 中携带 Authorization
- 文件会在服务器保留 7 天后自动删除
- 批量处理任务会返回 ZIP 压缩包
功能参数参考
以下是所有 53 个处理功能的详细参数说明。点击类别筛选查看对应功能。
错误处理
API 返回的错误信息遵循统一格式:
{
"success": false,
"error": "错误描述信息"
}| 状态码 | 说明 | 常见原因 |
|---|---|---|
200 | 成功 | 请求处理成功 |
400 | 请求参数错误 | 缺少必填参数、参数格式错误 |
401 | 认证失败 | API 密钥无效或已撤销 |
403 | 权限不足 | 无 API 权限、文件不属于当前用户 |
404 | 资源不存在 | 任务不存在、文件不存在 |
429 | 请求过于频繁 | 超出频率限制、并发任务数已满 |
500 | 服务器错误 | 服务器内部错误,请联系管理员 |
限制说明
- API 调用:100 次/分钟
- 文件上传:20 次/分钟
- 任务创建:50 次/分钟
- API 密钥:最多 10 个/用户
- 并发任务:根据 VIP 等级
- 文件保留:7 天自动删除
- 普通用户:最大 100MB
- VIP 用户:最大 2GB
- 视频:MP4, AVI, MOV, MKV, WebM, FLV, WMV, M4V
- 音频:MP3, WAV, OGG, AAC, FLAC, M4A, WMA, AIFF
- 图像:JPG, PNG, WebP, GIF, BMP, TIFF, ICO
- 文档:PDF
完整示例
Python 完整示例
import requests
import time
API_KEY = "mp_your_api_key_here"
BASE_URL = "https://www.johngko.com"
headers = {"Authorization": f"Bearer {API_KEY}"}
def upload_file(file_path):
"""上传文件"""
with open(file_path, "rb") as f:
response = requests.post(
f"{BASE_URL}/api/v1/upload",
headers=headers,
files={"file": f}
)
result = response.json()
if result["success"]:
return result["data"]["file_id"]
raise Exception(f"Upload failed: {result.get('error')}")
def create_task(file_id, function_code, parameters=None):
"""创建处理任务"""
response = requests.post(
f"{BASE_URL}/api/v1/tasks",
headers=headers,
json={
"file_id": file_id,
"function_code": function_code,
"parameters": parameters or {}
}
)
result = response.json()
if result["success"]:
return result["data"]["task_id"]
raise Exception(f"Create task failed: {result.get('error')}")
def wait_for_task(task_id, timeout=300):
"""等待任务完成"""
start_time = time.time()
while time.time() - start_time < timeout:
response = requests.get(
f"{BASE_URL}/api/v1/tasks/{task_id}",
headers=headers
)
result = response.json()
if result["success"]:
data = result["data"]
status = data["status"]
if status == "COMPLETED":
return data
elif status == "FAILED":
raise Exception(f"Task failed: {data.get('error_message')}")
time.sleep(2)
raise Exception("Task timeout")
def download_result(task_id, output_path):
"""下载处理结果"""
response = requests.get(
f"{BASE_URL}/api/v1/tasks/{task_id}/download",
headers=headers
)
with open(output_path, "wb") as f:
f.write(response.content)
# 完整流程示例
if __name__ == "__main__":
# 1. 上传文件
file_id = upload_file("input.mp4")
print(f"File uploaded, ID: {file_id}")
# 2. 创建任务
task_id = create_task(
file_id,
"video_compress",
{"mode": "quality", "quality": "medium"}
)
print(f"Task created, ID: {task_id}")
# 3. 等待完成
result = wait_for_task(task_id)
print(f"Task completed: {result['output_filename']}")
# 4. 下载结果
download_result(task_id, "output.mp4")
print("Download completed!")Node.js 示例
const fs = require('fs');
const axios = require('axios');
const FormData = require('form-data');
const API_KEY = 'mp_your_api_key_here';
const BASE_URL = 'https://www.johngko.com';
const headers = { Authorization: `Bearer ${API_KEY}` };
async function uploadFile(filePath) {
const form = new FormData();
form.append('file', fs.createReadStream(filePath));
const response = await axios.post(`${BASE_URL}/api/v1/upload`, form, {
headers: { ...headers, ...form.getHeaders() }
});
if (response.data.success) {
return response.data.data.file_id;
}
throw new Error(`Upload failed: ${response.data.error}`);
}
async function createTask(fileId, functionCode, parameters = {}) {
const response = await axios.post(`${BASE_URL}/api/v1/tasks`, {
file_id: fileId,
function_code: functionCode,
parameters
}, { headers });
if (response.data.success) {
return response.data.data.task_id;
}
throw new Error(`Create task failed: ${response.data.error}`);
}
async function waitForTask(taskId, timeout = 300000) {
const startTime = Date.now();
while (Date.now() - startTime < timeout) {
const response = await axios.get(`${BASE_URL}/api/v1/tasks/${taskId}`, { headers });
if (response.data.success) {
const { status, error_message } = response.data.data;
if (status === 'COMPLETED') {
return response.data.data;
}
if (status === 'FAILED') {
throw new Error(`Task failed: ${error_message}`);
}
}
await new Promise(r => setTimeout(r, 2000));
}
throw new Error('Task timeout');
}
async function downloadResult(taskId, outputPath) {
const response = await axios.get(`${BASE_URL}/api/v1/tasks/${taskId}/download`, {
headers,
responseType: 'stream'
});
const writer = fs.createWriteStream(outputPath);
response.data.pipe(writer);
return new Promise((resolve, reject) => {
writer.on('finish', resolve);
writer.on('error', reject);
});
}
// 完整流程
(async () => {
const fileId = await uploadFile('input.mp4');
console.log(`File uploaded, ID: ${fileId}`);
const taskId = await createTask(fileId, 'video_compress', {
mode: 'quality',
quality: 'medium'
});
console.log(`Task created, ID: ${taskId}`);
const result = await waitForTask(taskId);
console.log(`Task completed: ${result.output_filename}`);
await downloadResult(taskId, 'output.mp4');
console.log('Download completed!');
})();常见问题
登录后进入「用户中心」→「API 密钥管理」,点击「创建密钥」即可生成。密钥仅显示一次,请务必保存。
处理时间取决于文件大小和处理类型。通常视频处理需要几秒到几分钟,图像处理通常在几秒内完成。
处理结果文件会在服务器保留 7 天,之后自动删除。请及时下载。
部分功能支持批量处理(如批量压缩、批量格式转换),使用 inputFileIds 参数传入多个文件ID即可。
请检查:1) API 密钥是否正确;2) 请求参数是否符合要求;3) 文件格式是否支持;4) 是否超出限制。如仍有问题,请联系技术支持。