API 文档

多媒体处理平台 RESTful API 接口文档

v1.0最后更新: 2026-03-01

概述

多媒体处理平台提供 RESTful API 接口,允许开发者通过 API 调用使用平台的所有核心功能。API 支持 JSON 格式的请求和响应。

Base URL
https://www.johngko.com
认证方式

所有 API 请求需要在 Header 中携带 API 密钥(Bearer Token):

Authorization: Bearer YOUR_API_KEY
支持格式
  • 请求格式: application/json
  • 响应格式: application/json
  • 文件上传: multipart/form-data

快速开始

1获取 API 密钥

登录用户中心,在「API 密钥管理」页面创建新的 API 密钥。密钥仅显示一次,请妥善保存。

前往创建 API 密钥
2上传文件

使用 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"
3创建处理任务

使用 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"}}'
4查询任务状态并下载

轮询 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 密钥。

请求头
AuthorizationBearer YOUR_API_KEY必填,API 密钥
Content-Typeapplication/jsonPOST/PUT 请求必填
认证错误响应
状态码错误信息说明
401缺少认证信息未提供 Authorization 头
401无效的 API 密钥密钥格式错误或不存在
401API 密钥已被撤销密钥已被用户撤销
403无 API 使用权限账户未开通 API 权限

API 端点

GET/api/v1/functions获取功能列表

获取所有可用的处理功能列表及其参数定义。

响应字段
字段类型说明
successboolean请求是否成功
data.functionsarray功能列表
data.totalnumber功能总数
data.is_vipboolean是否为 VIP 用户
响应示例
{
  "success": true,
  "data": {
    "functions": [
      {
        "code": "video_compress",
        "name": "视频压缩",
        "category": "VIDEO",
        "description": "通过调节质量参数压缩视频体积",
        "available": true
      }
    ],
    "total": 53,
    "is_vip": true
  }
}
POST/api/v1/upload上传文件

上传待处理的文件,支持视频、音频、图像、文档等格式。

请求参数 (multipart/form-data)
参数类型必填说明
fileFile要上传的文件
响应字段
字段类型说明
data.file_idnumber文件ID,用于后续任务创建
data.file_typestring文件类型: VIDEO, AUDIO, IMAGE, DOCUMENT
data.filenamestring原始文件名
data.file_sizenumber文件大小(字节)
响应示例
{
  "success": true,
  "data": {
    "file_id": 123,
    "file_type": "VIDEO",
    "filename": "example.mp4",
    "file_size": 10485760,
    "mime_type": "video/mp4"
  }
}
POST/api/v1/tasks创建处理任务

创建文件处理任务,任务将进入队列异步处理。

请求参数 (JSON Body)
参数类型必填说明
file_idnumber上传文件返回的文件ID
function_codestring功能代码,如 video_compress
parametersobject处理参数,详见功能参数参考
响应字段
字段类型说明
data.task_idnumber任务ID,用于查询状态
data.task_nostring任务编号
data.statusstring任务状态: QUEUED, PROCESSING, COMPLETED, FAILED
data.concurrent_infoobject并发信息
响应示例
{
  "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
    }
  }
}
GET/api/v1/tasks/:id查询任务状态

查询指定任务的详细信息和处理状态。

路径参数
参数类型说明
idnumber任务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"
  }
}
GET/api/v1/tasks/:id/download下载处理结果

下载处理完成的文件。仅当任务状态为 COMPLETED 时可用。

响应

成功时返回文件流(Content-Type 根据文件类型设置),失败时返回 JSON 错误信息。

注意事项
  • 下载链接需要在 Header 中携带 Authorization
  • 文件会在服务器保留 7 天后自动删除
  • 批量处理任务会返回 ZIP 压缩包

功能参数参考

以下是所有 53 个处理功能的详细参数说明。点击类别筛选查看对应功能。

错误处理

API 返回的错误信息遵循统一格式:

{
  "success": false,
  "error": "错误描述信息"
}
HTTP 状态码
状态码说明常见原因
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!');
})();

常见问题

Q: 如何获取 API 密钥?

登录后进入「用户中心」→「API 密钥管理」,点击「创建密钥」即可生成。密钥仅显示一次,请务必保存。

Q: 任务处理需要多长时间?

处理时间取决于文件大小和处理类型。通常视频处理需要几秒到几分钟,图像处理通常在几秒内完成。

Q: 处理结果会保存多久?

处理结果文件会在服务器保留 7 天,之后自动删除。请及时下载。

Q: 如何处理批量文件?

部分功能支持批量处理(如批量压缩、批量格式转换),使用 inputFileIds 参数传入多个文件ID即可。

Q: 遇到错误如何排查?

请检查:1) API 密钥是否正确;2) 请求参数是否符合要求;3) 文件格式是否支持;4) 是否超出限制。如仍有问题,请联系技术支持。