1. 接口概述

本 API 提供基于 Sanjuuni 的媒体转换服务，支持从视频/图片 URL 提取并转换格式。

2. 基础信息

• 接口地址: http://newgmapi.liulikeji.cn/api/sanjuuni

• 请求方法: POST

• 请求格式: JSON

• 响应格式: JSON

3. 请求参数

参数名 类型 必填 说明 示例
input_url string 是 输入文件的URL地址 "http://example.com/audio.mp3"
args array 是 处理参数 ["-8", "--width=32", "--height=32"]
output_format string 是 输出格式 "lua"

常用参数示例

    // 使用八叉树算法转换为高32宽32像素的“单帧”lua文件
{
    "args": ["-8","--width=32","--height=32"],
    "output_format": "lua"
}
    
    // 输出blit图像(BIMG)格式的图片/动画文件
{
    "args": [],
    "output_format": "bimg"
}
    
    // 输出带压缩和音频的32vid格式二进制视频文件
{
    "args": [],
    "output_format": "32vid"
}

4. 响应参数

参数名 类型 说明
status string 处理状态 ("success"/"error")
download_url string 完整下载URL
file_id string 文件唯一标识符
error string 错误信息(仅失败时返回)

成功响应示例

{

    "status": "success",

    "download_url": "http://your-server/download/3cff4a16/3cff4a16.lua",

    "file_id": "3cff4a16"

}

失败响应示例

{

    "status": "error",

    "error": "Invalid input URL"

}

5. 状态码说明

状态码 说明
200 处理成功
400 请求参数错误
403 参数安全检查失败
404 文件不存在
500 服务器内部错误

6. 使用示例

Demo1：CCTweaked-Demo/demo1.lua

运行：wget run https://git.liulikeji.cn/xingluo/CCTweaked-Demo/raw/branch/main/Demo/SanjuuniApi-Demo/demo1.lua

作用：将CCTweaked-Demo/demo.jpg 转换为当前屏幕尺寸的lua单帧图片并保存为demo.lua

可选：你可以直接将Get_image_url函数用在你的代码里，也可以对文件进行改造，包括你可以将其改为直接运行而非存储（注释掉保存的代码，还原直接运行代码）

Demo2：CCTweaked-Demo/demo2.lua

下载：wget https://git.liulikeji.cn/xingluo/CCTweaked-Demo/raw/branch/main/Demo/SanjuuniApi-Demo/demo2.lua

作用：自动转工具

参数：

选项 是否可选 说明
--url 必填 输入图片的URL地址
--format 必填 指定输出格式（如 bimg、lua 等）
--out 必填 输出文件的保存路径
--args 可选 自定义转换参数（如 '-8'、'-k'）
--monitor 可选 使用指定显示器（如 top、monitor_0）作为尺寸参考
--scale 可选 在获取显示器尺寸前设置显示比例（如 0.5）
--help 可选 显示帮助信息

示例：

#转换demo.jpg为demo.lua直接可执行文件

demo2.lua --url https://git.liulikeji.cn/xingluo/CCTweaked-Demo/raw/branch/main/Demo/SanjuuniApi-Demo/demo.jpg --format lua --out demo.lua


#以上方显示器缩放到0.25的尺寸转换demo.gif为demo.bimg文件 (可通过bimg-play.lua播放)

demo2.lua --url https://git.liulikeji.cn/xingluo/CCTweaked-Demo/raw/branch/main/Demo/SanjuuniApi-Demo/demo.gif --format bimg --out demo.bimg --monitor top --scale 0.25


#转换demo.mp4为demo.32vid文件 (可通过https://git.liulikeji.cn/xingluo/CCTweaked-utils/src/branch/main/32vid/32vid-player-mini.lua播放)  注：过大的视频转换时间会很长导致http请求超时

demo2.lua --url https://git.liulikeji.cn/xingluo/CCTweaked-Demo/raw/branch/main/Demo/SanjuuniApi-Demo/demo.mp4 --format bimg --out demo.32vid

Bimg播放工具：CCTweaked-utils/bimg-play.lua

下载：wget http://git.liulikeji.cn/xingluo/CCTweaked-utils/raw/branch/main/bimg/bimg-play.lua

作用：播放bimg格式图像

选项 是否可选 说明
<file.bimg> 必填 要播放的 .bimg 文件路径
--loop 可选 循环播放动画
--url 可选 从 URL 加载 .bimg 文件
--monitor <side> 可选 在指定显示器上播放（支持 top/monitor_1）
--scale <num> 可选 设置显示比例（3-0.25）
--fps <num> 可选 设置帧率（1-60）
--help 可选 显示帮助信息

7. 完整输入参数和格式

输出格式选项

选项 说明
lua 输出Lua脚本（图像默认，仅单帧）
nfp 输出NFP格式图像（会改变比例）
raw 输出rawmode格式文件
bimg 输出BIMG格式（视频默认）
32vid 输出32vid格式（带压缩+音频）

调色板选项

选项 说明
-p, --default-palette 使用默认CC调色板
-P, --palette=palette 使用自定义调色板
-t, --threshold 使用阈值处理替代抖动
-O, --ordered 使用有序抖动
-L, --lab-color 使用CIELAB色彩空间
-8, --octree 使用八叉树算法（较慢）
-k, --kmeans 使用k均值算法（最慢）

高级选项

选项 说明
-c, --compression=mode 压缩类型：none/ans/deflate/custom
-B, --binary 二进制格式输出BIMG文件
-S, --separate-streams 32vid使用分离流（解码慢）
-d, --dfpwm 对音频使用DFPWM压缩
-m, --mute 移除音频
-W, --width=size 调整图像宽度
-H, --height=size 调整图像高度
-M, --monitor-size[=WxH[@S]] 为大型显示器分割图像
--trim-borders 跳过被显示器边框遮挡的像素
-h, --help 显示帮助信息

8. 注意事项

1. 文件下载链接有效期为2小时