API 接口

本文介绍系统的 RESTful API 接口。

API 概述

基础信息

项目	说明
基础 URL	`https://your-domain.com/api`
协议	HTTPS
数据格式	JSON
字符编码	UTF-8

响应格式

所有 API 响应格式统一：

json

{
  "code": 0,           // 状态码，0 表示成功
  "message": "success", // 状态信息
  "data": {}           // 响应数据
}

错误码

错误码	说明
0	成功
400	请求参数错误
401	未授权
403	权限不足
404	资源不存在
500	服务器内部错误

认证方式

JWT Token

大多数 API 需要在请求头中携带 JWT Token：

bash

Authorization: Bearer <your_token>

API Key

对于服务端调用，可使用 API Key：

bash

X-API-Key: <your_api_key>
X-Timestamp: 1704067200
X-Sign: <signature>

签名算法：

javascript

sign = sha256(api_key + timestamp + secret_key)

用户接口

用户登录

http

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "password123"
}

响应：

json

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expire": 1704153600,
    "user": {
      "id": 1,
      "username": "admin",
      "nickname": "管理员",
      "avatar": "/avatars/1.jpg"
    }
  }
}

用户注册

http

POST /api/auth/register
Content-Type: application/json

{
  "username": "newuser",
  "password": "password123",
  "email": "user@example.com",
  "invite_code": "ABC123"  // 可选
}

获取用户信息

http

GET /api/user/profile
Authorization: Bearer <token>

响应：

json

{
  "code": 0,
  "data": {
    "id": 1,
    "username": "admin",
    "nickname": "管理员",
    "email": "admin@example.com",
    "avatar": "/avatars/1.jpg",
    "vip_level": 2,
    "vip_expire": "2024-12-31",
    "points": 1000,
    "created_at": "2024-01-01 00:00:00"
  }
}

修改用户信息

http

PUT /api/user/profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "nickname": "新昵称",
  "avatar": "/avatars/new.jpg"
}

视频接口

获取视频列表

http

GET /api/videos?page=1&size=20&category_id=1&keyword=搜索词
Authorization: Bearer <token>

参数：

参数	类型	必须	说明
page	int	否	页码，默认 1
size	int	否	每页数量，默认 20
category_id	int	否	分类 ID
keyword	string	否	搜索关键词
status	int	否	状态：1-已发布
order	string	否	排序：views/created_at

响应：

json

{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "title": "示例视频",
        "description": "视频描述",
        "cover": "/covers/1.jpg",
        "duration": 3600,
        "views": 1000,
        "category": {
          "id": 1,
          "name": "电影"
        },
        "created_at": "2024-01-01 00:00:00"
      }
    ],
    "total": 100,
    "page": 1,
    "size": 20
  }
}

获取视频详情

http

GET /api/videos/{id}
Authorization: Bearer <token>

响应：

json

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "示例视频",
    "description": "视频描述",
    "cover": "/covers/1.jpg",
    "play_url": "/videos/1/index.m3u8",
    "duration": 3600,
    "resolution": "1080p",
    "file_size": 1073741824,
    "views": 1000,
    "category": {
      "id": 1,
      "name": "电影"
    },
    "tags": ["动作", "科幻"],
    "created_at": "2024-01-01 00:00:00"
  }
}

上传视频

http

POST /api/videos/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <video_file>
title: 视频标题
description: 视频描述
category_id: 1

响应：

json

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "视频标题",
    "status": "pending",  // 等待转码
    "upload_progress": 100
  }
}

分片上传

初始化上传

http

POST /api/videos/upload/init
Authorization: Bearer <token>
Content-Type: application/json

{
  "filename": "video.mp4",
  "filesize": 1073741824,
  "title": "视频标题",
  "category_id": 1
}

响应：

json

{
  "code": 0,
  "data": {
    "upload_id": "abc123",
    "chunk_size": 5242880,
    "total_chunks": 205
  }
}

上传分片

http

POST /api/videos/upload/chunk
Authorization: Bearer <token>
Content-Type: multipart/form-data

upload_id: abc123
chunk_index: 0
chunk: <chunk_data>

完成上传

http

POST /api/videos/upload/complete
Authorization: Bearer <token>
Content-Type: application/json

{
  "upload_id": "abc123"
}

编辑视频

http

PUT /api/videos/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "新标题",
  "description": "新描述",
  "category_id": 2,
  "tags": ["动作", "冒险"]
}

删除视频

http

DELETE /api/videos/{id}
Authorization: Bearer <token>

分类接口

获取分类列表

http

GET /api/categories

响应：

json

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "name": "电影",
      "parent_id": 0,
      "sort": 1,
      "children": [
        {
          "id": 2,
          "name": "动作片",
          "parent_id": 1,
          "sort": 1
        }
      ]
    }
  ]
}

创建分类

http

POST /api/admin/categories
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "新分类",
  "parent_id": 0,
  "sort": 1
}

更新分类

http

PUT /api/admin/categories/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "分类新名称",
  "sort": 2
}

删除分类

http

DELETE /api/admin/categories/{id}
Authorization: Bearer <token>

转码接口

获取转码任务列表

http

GET /api/admin/transcode/tasks?page=1&size=20&status=pending
Authorization: Bearer <token>

状态值：

pending - 等待中
processing - 转码中
completed - 已完成
failed - 失败

获取转码任务详情

http

GET /api/admin/transcode/tasks/{id}
Authorization: Bearer <token>

响应：

json

{
  "code": 0,
  "data": {
    "id": 1,
    "video_id": 1,
    "status": "processing",
    "progress": 45,
    "started_at": "2024-01-01 10:00:00",
    "log": "转码日志..."
  }
}

重试转码任务

http

POST /api/admin/transcode/tasks/{id}/retry
Authorization: Bearer <token>

取消转码任务

http

POST /api/admin/transcode/tasks/{id}/cancel
Authorization: Bearer <token>

统计接口

概览数据

http

GET /api/admin/statistics/overview
Authorization: Bearer <token>

响应：

json

{
  "code": 0,
  "data": {
    "total_videos": 1000,
    "total_users": 500,
    "total_views": 100000,
    "storage_used": 107374182400,
    "today": {
      "new_videos": 10,
      "new_users": 5,
      "views": 1000
    }
  }
}

视频统计

http

GET /api/admin/statistics/videos?start_date=2024-01-01&end_date=2024-01-31
Authorization: Bearer <token>

用户统计

http

GET /api/admin/statistics/users?start_date=2024-01-01&end_date=2024-01-31
Authorization: Bearer <token>

设置接口

获取系统设置

http

GET /api/admin/settings
Authorization: Bearer <token>

更新系统设置

http

PUT /api/admin/settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "site_name": "米卡云转码",
  "site_url": "https://example.com"
}

错误处理

错误响应示例

json

{
  "code": 400,
  "message": "参数错误",
  "errors": {
    "username": "用户名不能为空",
    "password": "密码长度至少 8 位"
  }
}

常见错误

HTTP 状态码	错误码	说明
400	400	请求参数错误
401	401	Token 无效或过期
403	403	无权限访问
404	404	资源不存在
429	429	请求过于频繁
500	500	服务器内部错误

SDK 示例

JavaScript

javascript

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://your-domain.com/api',
  timeout: 30000
});

// 请求拦截器
api.interceptors.request.use(config => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// 获取视频列表
async function getVideos(page = 1, size = 20) {
  const response = await api.get('/videos', {
    params: { page, size }
  });
  return response.data;
}

// 上传视频
async function uploadVideo(file, title, categoryId) {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('title', title);
  formData.append('category_id', categoryId);
  
  const response = await api.post('/videos/upload', formData, {
    headers: { 'Content-Type': 'multipart/form-data' },
    onUploadProgress: (progress) => {
      console.log(`上传进度: ${Math.round(progress.loaded / progress.total * 100)}%`);
    }
  });
  return response.data;
}

Python

python

import requests

class MikaAPI:
    def __init__(self, base_url, token=None):
        self.base_url = base_url
        self.token = token
        
    def _headers(self):
        headers = {'Content-Type': 'application/json'}
        if self.token:
            headers['Authorization'] = f'Bearer {self.token}'
        return headers
    
    def login(self, username, password):
        response = requests.post(
            f'{self.base_url}/auth/login',
            json={'username': username, 'password': password}
        )
        data = response.json()
        if data['code'] == 0:
            self.token = data['data']['token']
        return data
    
    def get_videos(self, page=1, size=20):
        response = requests.get(
            f'{self.base_url}/videos',
            params={'page': page, 'size': size},
            headers=self._headers()
        )
        return response.json()
    
    def upload_video(self, file_path, title, category_id):
        with open(file_path, 'rb') as f:
            files = {'file': f}
            data = {'title': title, 'category_id': category_id}
            response = requests.post(
                f'{self.base_url}/videos/upload',
                files=files,
                data=data,
                headers={'Authorization': f'Bearer {self.token}'}
            )
        return response.json()

# 使用示例
api = MikaAPI('https://your-domain.com/api')
api.login('admin', 'password123')
videos = api.get_videos()

下一步

常见问题 - FAQ
系统配置 - 配置详解
视频转码 - 转码功能

API 接口 ​

API 概述 ​

基础信息 ​

响应格式 ​

错误码 ​

认证方式 ​

JWT Token ​

API Key ​

用户接口 ​

用户登录 ​

用户注册 ​

获取用户信息 ​

修改用户信息 ​

视频接口 ​

获取视频列表 ​

获取视频详情 ​

上传视频 ​

分片上传 ​

初始化上传 ​

上传分片 ​

完成上传 ​

编辑视频 ​

删除视频 ​

分类接口 ​

获取分类列表 ​

创建分类 ​

更新分类 ​

删除分类 ​

转码接口 ​

获取转码任务列表 ​

获取转码任务详情 ​

重试转码任务 ​

取消转码任务 ​

统计接口 ​

概览数据 ​

视频统计 ​

用户统计 ​

设置接口 ​

获取系统设置 ​

更新系统设置 ​

错误处理 ​

错误响应示例 ​

常见错误 ​

SDK 示例 ​

JavaScript ​

Python ​

下一步 ​

API 接口

API 概述

基础信息

响应格式

错误码

认证方式

JWT Token

API Key

用户接口

用户登录

用户注册

获取用户信息

修改用户信息

视频接口

获取视频列表

获取视频详情

上传视频

分片上传

初始化上传

上传分片

完成上传

编辑视频

删除视频

分类接口

获取分类列表

创建分类

更新分类

删除分类

转码接口

获取转码任务列表

获取转码任务详情

重试转码任务

取消转码任务

统计接口

概览数据

视频统计

用户统计

设置接口

获取系统设置

更新系统设置

错误处理

错误响应示例

常见错误

SDK 示例

JavaScript

Python

下一步