NodeODM 中文 API 文档
版本 ：2.2.1
描述 ：用于访问 OpenDroneMap (ODM) 的 REST API
许可证 ：AGPL-3.0
联系人 ：Piero Toffanin
概述
NodeODM 是一个基于 REST 的 API 服务，用于与 OpenDroneMap 处理引擎交互，支持上传图像、配置处理选项、启动任务、监控进度并下载处理结果。
认证
部分接口支持通过 token 查询参数进行身份验证。如需登录或注册，请参考 /auth/login 与 /auth/register 接口。
任务（Task）相关接口
初始化新任务
POST /task/new/init
初始化一个新任务的上传流程。成功后，可通过 /task/new/upload 上传文件，任务不会立即开始，需调用 /task/new/commit 才会真正启动。
请求参数（formData）
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 否 | 任务的可选名称 |
options | string | 否 | 序列化的 JSON 字符串，格式为：[{name: "option1", value: "value1"}, ...]。可通过 /options 获取所有可用选项 |
skipPostProcessing | boolean | 否 | 若设置，则跳过点云瓦片生成 |
webhook | string | 否 | 处理完成后（无论成功或失败）回调的 URL |
outputs | string | 否 | 序列化的 JSON 字符串，指定应包含在 all.zip 中的文件路径（相对于项目目录），用于覆盖默认行为 |
dateCreated | integer | 否 | 可选的时间戳，覆盖任务默认创建时间 |
token | string (query) | 否 | 身份验证令牌（如启用认证） |
set-uuid | string (header) | 否 | 可选的 UUID，用于指定任务 ID，而非自动生成 |
成功响应（200）
{
"uuid": "任务唯一标识符"
}
上传任务文件
POST /task/new/upload/{uuid}
向已初始化的任务上传图像及其他可选文件（如 GCP、geo.txt、seed.zip 等）。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
uuid | path | string | 是 | 任务 UUID |
images | formData | file | 是 | 要处理的图像文件，以及可选的辅助文件（如 geo.txt、image_groups.txt、GCP 文件 *.txt、seed.zip、align.las/laz/tif 等） |
token | query | string | 否 | 身份验证令牌 |
成功响应（200）
{
"success": true
}
提交并启动任务
POST /task/new/commit/{uuid}
提交已上传文件的任务并加入处理队列。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
uuid | path | string | 是 | 任务 UUID |
token | query | string | 否 | 身份验证令牌 |
成功响应（200）
{
"uuid": "任务唯一标识符"
}
一键创建并启动任务
POST /task/new
适用于较小任务，可直接上传文件或提供 ZIP 文件 URL 并立即启动处理。
请求参数（multipart/form-data）
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
images | file | 否 | 图像及其他辅助文件（同上） |
zipurl | string | 否 | 包含图像的 ZIP 文件 URL（可选包含 geo.txt 或 GCP 文件） |
name | string | 否 | 任务名称 |
options | string | 否 | 处理选项（JSON 字符串） |
skipPostProcessing | boolean | 否 | 跳过点云瓦片生成 |
webhook | string | 否 | 回调 URL |
outputs | string | 否 | 自定义输出文件列表（JSON 字符串） |
dateCreated | integer | 否 | 自定义创建时间戳 |
token | string (query) | 否 | 身份验证令牌 |
set-uuid | string (header) | 否 | 指定任务 UUID |
成功响应（200）
{
"uuid": "任务唯一标识符"
}
获取任务列表
GET /task/list
获取当前节点上所有任务的 UUID 列表。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
token | query | string | 否 | 身份验证令牌 |
成功响应（200）
[
{ "uuid": "uuid1" },
{ "uuid": "uuid2" }
]
获取任务信息
GET /task/{uuid}/info
获取指定任务的详细信息，包括状态、处理时间、图像数量、选项等。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
uuid | path | string | 是 | 任务 UUID |
token | query | string | 否 | 身份验证令牌 |
with_output | query | integer | 否 | 可选，指定从第几行开始返回控制台输出（默认 0，不返回） |
成功响应（200）
{
"uuid": "任务ID",
"name": "任务名称",
"dateCreated": 1700000000,
"processingTime": 12345,
"status": { "code": 20 },
"options": [
{ "name": "odm_meshing-octreeDepth", "value": "9" }
],
"imagesCount": 150,
"progress": 45.6,
"output": ["line1", "line2", ...] // 仅当 with_output 被指定时存在
}
状态码说明 ：
10：排队中（QUEUED）20：运行中（RUNNING）30：失败（FAILED）40：已完成（COMPLETED）50：已取消（CANCELED）
获取任务控制台输出
GET /task/{uuid}/output
获取任务的实时控制台输出日志。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
uuid | path | string | 是 | 任务 UUID |
line | query | integer | 否 | 从第几行开始返回（默认 0，返回全部） |
token | query | string | 否 | 身份验证令牌 |
成功响应（200）
纯文本格式的控制台输出内容。
下载任务结果
GET /task/{uuid}/download/{asset}
下载任务处理结果。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
uuid | path | string | 是 | 任务 UUID |
asset | path | string | 是 | 资产类型，目前仅支持 "all.zip" |
token | query | string | 否 | 身份验证令牌 |
成功响应（200）
返回 ZIP 文件（application/zip）。
取消任务
POST /task/cancel
取消正在运行或排队中的任务。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
uuid | body | string | 是 | 任务 UUID |
token | query | string | 否 | 身份验证令牌 |
成功响应（200）
{
"success": true
}
删除任务
POST /task/remove
彻底删除任务及其所有资产文件。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
uuid | body | string | 是 | 任务 UUID |
token | query | string | 否 | 身份验证令牌 |
成功响应（200）
{
"success": true
}
重启任务
POST /task/restart
重新启动一个已取消、失败或已完成的任务（可选覆盖处理选项）。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
uuid | body | string | 是 | 任务 UUID |
options | body | string | 否 | 新的处理选项（JSON 字符串） |
token | query | string | 否 | 身份验证令牌 |
成功响应（200）
{
"success": true
}
服务（Server）相关接口
获取处理选项列表
GET /options
获取所有可用的 ODM 处理命令行选项。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
token | query | string | 否 | 身份验证令牌 |
成功响应（200）
[
{
"name": "odm_meshing-octreeDepth",
"type": "int",
"value": "9",
"domain": "positive integer",
"help": "控制网格重建的细节级别"
},
...
]
获取节点信息
GET /info
获取当前 NodeODM 节点的系统与服务信息。
请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
token | query | string | 否 | 身份验证令牌 |
成功响应（200）
{
"version": "2.2.1",
"taskQueueCount": 3,
"availableMemory": 8589934592,
"totalMemory": 17179869184,
"cpuCores": 8,
"maxImages": 10000,
"maxParallelTasks": 2,
"engineVersion": "3.2.0",
"engine": "opendronemap"
}
认证（Auth）相关接口
获取登录信息
GET /auth/info
获取登录/注册相关说明及链接。
成功响应（200）
{
"message": "请登录以使用此服务。",
"loginUrl": "/auth/login",
"registerUrl": "/auth/register"
}
若未启用认证，
loginUrl和registerUrl可能为null。
用户登录
POST /auth/login
通过用户名和密码获取访问令牌。
请求体（JSON）
{
"username": "your_username",
"password": "your_password"
}
成功响应（200）
{
"token": "your_access_token"
}
用户注册
POST /auth/register
注册新用户。
请求体（JSON）
{
"username": "new_user",
"password": "secure_password"
}
成功响应（200）
{
"success": true
}
通用响应结构
错误响应（Error）
{
"error": "错误描述信息"
}
通用响应（Response）
{
"success": true, // 或 false
"error": "错误信息" // 仅当 success 为 false 时存在
}
文档基于 Swagger 2.0 规范生成，适用于 NodeODM v2.2.1。
最后更新：2025年11月3日