远程模型 API 接口文档

基础信息

默认端口: 由配置文件中的 LAUNCHER_PORT 指定
数据目录: launcher-data/（用于文件上传和下载）
响应格式: JSON

接口列表

1. 健康检查

接口地址: /ping
请求方法: GET
接口描述: 检查服务是否正常运行

请求参数

无

响应示例

{
"code": 0,
"msg": "ok",
"data": {}
}

2. 获取配置信息

接口地址: /config
请求方法: POST
接口描述: 获取当前启动器的配置信息

请求参数

无

响应示例

{
"code": 0,
"msg": "ok",
"data": {
"name": "服务名称",
"version": "1.0.0",
"launcher": {
"entry": "启动命令",
"entryArgs": ["参数1", "参数2"],
"envs": ["ENV_VAR=value"]
}
}
}

3. 提交任务

接口地址: /submit
请求方法: POST
接口描述: 提交一个新的执行任务

请求参数

{
"entry": "执行命令路径（可选，默认使用配置文件中的 entry）",
"entryArgs": ["命令参数数组（可选，默认使用配置文件中的 entryArgs）"],
"entryPlaceholders": {
"占位符key": "替换值"
},
"envs": {
"环境变量key": "环境变量value"
},
"root": "工作目录（可选，默认使用配置的 Root）"
}

参数说明

entry: 要执行的命令或脚本路径
entryArgs: 命令参数数组
entryPlaceholders: 占位符替换映射，会将 entry 和 entryArgs 中的 ${key} 替换为对应的值
envs: 自定义环境变量
root: 命令执行的工作目录

响应示例

{
"code": 0,
"msg": "ok",
"data": {
"token": "64位随机字符串（用于查询任务状态）"
}
}

错误响应

{
"code": -1,
"msg": "错误信息",
"data": {}
}

4. 查询任务状态

接口地址: /query
请求方法: POST
接口描述: 根据 token 查询任务执行状态和日志

请求参数

{
"token": "任务 token（submit 接口返回）"
}

响应示例

{
"code": 0,
"msg": "ok",
"data": {
"logs": "Base64 编码的日志内容",
"status": "running | success | error"
}
}

状态说明

running: 任务正在执行中
success: 任务执行成功
error: 任务执行失败

注意事项

日志内容使用 Base64 编码
每次查询会返回自上次查询以来的新增日志
当任务状态为 success 或 error 时，token 会在返回后自动删除
如果 token 不存在，返回错误信息 "Token not found"

5. 取消任务

接口地址: /cancel
请求方法: POST
接口描述: 强制终止当前正在运行的任务

请求参数

无

响应示例

{
"code": 0,
"msg": "ok",
"data": {}
}

说明

该接口会终止当前正在运行的进程
如果没有正在运行的任务，调用此接口也会返回成功

6. 上传文件

接口地址: /upload
请求方法: POST
请求类型: multipart/form-data
接口描述: 上传文件到服务器

请求参数

file: 文件字段（通过 form-data 上传）

响应示例

{
"code": 0,
"msg": "ok",
"data": {
"file": "/launcher-data/随机文件名.ext"
}
}

说明

文件会被保存到 launcher-data/ 目录
文件名会被替换为 16 位随机字符串 + 原始扩展名
返回的文件路径可用于后续的任务提交或下载

7. 下载文件

接口地址: /download/:file
请求方法: GET
接口描述: 下载指定文件（下载后自动删除）

URL 参数

file: 文件名（不包含路径，仅文件名部分）

示例

GET /download/abc123def456.txt

响应

成功：返回文件流（application/octet-stream）
失败：返回 404 错误

说明

文件下载完成后会自动从服务器删除
仅能下载 launcher-data/ 目录下的文件
如果文件不存在，返回 404 错误

静态文件访问

路径: /launcher-data/*
方法: GET
描述: 直接访问 launcher-data 目录下的文件

示例

GET /launcher-data/example.txt

统一响应格式

所有接口统一返回以下格式：

{
"code": 0,
"msg": "消息描述",
"data": {}
}

字段说明

code: 状态码，0 表示成功，-1 表示失败
msg: 消息描述，成功时通常为 "ok"，失败时为具体错误信息
data: 返回数据，成功时包含实际数据，失败时为空对象 {}

使用流程示例

典型任务执行流程

健康检查

curl http://localhost:8888/ping

提交任务

curl -X POST http://localhost:8888/submit \
-H "Content-Type: application/json" \
-d '{
"entryArgs": ["--input", "test.wav"],
"envs": {
"DEBUG": "true"
}
}'

获得响应：{"code": 0, "msg": "ok", "data": {"token": "abc123..."}}

循环查询任务状态

curl -X POST http://localhost:8888/query \
-H "Content-Type: application/json" \
-d '{
"token": "abc123..."
}'

根据返回的 status 判断任务是否完成

（可选）取消任务

curl -X POST http://localhost:8888/cancel

文件上传和下载流程

上传文件

curl -X POST http://localhost:8888/upload \
-F "file=@/path/to/local/file.txt"

获得响应：{"code": 0, "msg": "ok", "data": {"file": "/launcher-data/abc123.txt"}}

使用上传的文件提交任务

curl -X POST http://localhost:8888/submit \
-H "Content-Type: application/json" \
-d '{
"entryPlaceholders": {
"INPUT_FILE": "/launcher-data/abc123.txt"
}
}'

下载结果文件

curl -O http://localhost:8888/download/result123.txt

注意事项

任务 Token 有效期: 任务 token 默认有效期为 24 小时，过期后会自动清理
并发限制: 当前实现只支持单个任务执行，新任务会覆盖正在运行的任务
日志获取: 使用 /query 接口时，每次只返回增量日志，需要客户端自行拼接
文件清理: 通过 /download 接口下载的文件会在下载后自动删除
环境变量: 系统会自动注入 AIGCPANEL_SERVER_ 前缀的环境变量
内存监控: 任务执行过程中会监控峰值内存使用情况
日志编码: 查询接口返回的日志内容使用 Base64 编码，需要解码后使用