接口概述

本文档介绍了异步任务处理系统的API接口，包括FFmpeg和Sanjuuni的异步处理接口，以及任务状态查询接口。

接口详情

1. 创建异步FFmpeg任务

接口地址: POST /api/ffmpeg/async

功能描述: 创建一个异步FFmpeg转换任务，立即返回任务ID和状态查询URL。

输入参数 (JSON格式)

参数名 类型 必选 描述 示例
input_url string 是 输入文件的URL地址 "https://example.com/input.mp4"
output_format string 是 输出文件格式 "mp3", "mp4", "avi"
args array 否 FFmpeg参数列表 ["-b:a", "192k", "-vn"]

输出参数

参数名 类型 描述 示例
status string 请求状态 "success"
task_id string 任务ID "a1b2c3d4"
status_url string 任务状态查询URL "http://localhost:5000/api/task/a1b2c3d4"
message string 提示信息 "任务已创建，请使用状态URL查询进度"

2. 创建异步Sanjuuni任务

接口地址: POST /api/sanjuuni/async

功能描述: 创建一个异步Sanjuuni转换任务，立即返回任务ID和状态查询URL。

输入参数 (JSON格式)

参数名 类型 必选 描述 示例
input_url string 是 输入文件的URL地址 "https://example.com/input.wav"
output_format string 是 输出文件格式 "lua", "nfp", "raw"
args array 否 Sanjuuni参数列表 []

输出参数
同FFmpeg异步任务接口。

3. 查询任务状态

接口地址: GET /api/task/<task_id>

功能描述: 查询指定任务的状态和进度，自动返回新增的日志信息。

路径参数

参数名 类型 必选 描述 示例
task_id string 是 任务ID "a1b2c3d4"

输出参数

参数名 类型 描述 示例
task_id string 任务ID "a1b2c3d4"
status string 任务状态 "pending", "running", "completed", "error"
type string 任务类型 "ffmpeg", "sanjuuni"
create_time float 任务创建时间戳 1690000000.123
start_time float 任务开始时间戳 1690000001.456
end_time float 任务结束时间戳 1690000010.789
progress int 任务进度百分比 75
total_logs int 总日志条数 15
new_logs array 新增日志列表 ["[时间] 日志内容"]
last_index int 当前日志总数 15
result object 任务完成时的结果 {"download_url": "...", "file_id": "..."}
error string 任务失败时的错误信息 "文件下载失败"

Python调用示例

1. 简单轮询示例

import requests
import time

def simple_async_conversion():
    """简单的异步转换示例"""
    base_url = "http://newgmapi.liulikeji.cn"
    
    # 创建FFmpeg任务
    task_data = {
        "input_url": "http://example.com/audio.mp3",
        "output_format": "mp3",
        "args": ["-b:a", "192k"]
    }
    
    response = requests.post(f"{base_url}/api/ffmpeg/async", json=task_data)
    if response.status_code != 202:
        print("创建任务失败")
        return
    
    task_info = response.json()
    task_id = task_info['task_id']
    print(f"任务已创建: {task_id}")
    
    # 轮询任务状态
    while True:
        status_response = requests.get(f"{base_url}/api/task/{task_id}")
        if status_response.status_code != 200:
            print("查询任务状态失败")
            break
            
        status = status_response.json()
        
        # 打印新增日志
        if 'new_logs' in status:
            for log in status['new_logs']:
                print(log)
        
        # 检查任务状态
        if status['status'] == 'completed':
            print("任务完成!")
            print(f"下载URL: {status['result']['download_url']}")
            break
        elif status['status'] == 'error':
            print(f"任务失败: {status.get('error', '未知错误')}")
            break
        else:
            print(f"任务进行中... 进度: {status.get('progress', 0)}%")
            time.sleep(2)  # 等待2秒后再次查询

# 运行示例
simple_async_conversion()

注意事项

  1. 任务状态: 任务状态包括 pending(等待中), running(进行中), completed(已完成), error(错误)

  2. 增量日志: 每次查询任务状态只会返回新增的日志，减少不必要的数据传输

  3. 超时处理: 任务和文件都有自动清理机制，长时间不访问的文件会被自动删除

  4. 错误处理: 建议在调用时添加适当的异常处理逻辑

这些接口提供了完整的异步任务处理能力，适合需要长时间运行的文件转换任务。