HTTP API 参考

在 Local Dream 中选定模型后，内嵌的 C++ 后端会在 127.0.0.1:8081 上提供 HTTP API。可以用它在同一台手机内（Termux）或从电脑（通过 adb forward）脚本化驱动 Local Dream。

最初的接口说明发布在 xororz/local-dream#45。本页根据后端 main.cpp 的当前实现整理所有参数。

前置条件

• 打开 Local Dream 并选定一个模型。后端只有在模型加载完成之后才会开始监听，并没有不经过模型加载就启动服务的方式。
• 服务仅绑定到 127.0.0.1，因此局域网中的其他设备无法直接访问，必须通过端口转发。

连接方式

从电脑通过 ADB 转发

adb forward tcp:8081 tcp:8081
# 此后电脑上 http://localhost:8081 即可访问后端。

在手机上通过 Termux

在 Termux 内直接运行脚本即可，localhost:8081 就是后端地址。

端点列表

方法	路径	用途
POST	/generate	执行一次生成，结果通过 SSE 流式返回
POST	/tokenize	计算提示词的 token 数（上限 77）

POST /generate

主要接口。请求体为 JSON，响应通过 Server-Sent Events 流式推送进度与最终图片（Content-Type: text/event-stream）。

请求字段

字段	类型	默认值	说明
prompt	string	必填	正向提示词。
negative_prompt	string	""	反向提示词。
steps	int	20	采样步数。
cfg	float	7.5	CFG 系数。在 NPU 模式下，cfg == 1.0 会触发跳过无条件 UNet 计算的优化。
seed	uint	随机	设置后可复现。
scheduler	string	"dpm"	详见下方 scheduler 取值列表。未知值会回退到 "dpm"。
size	int	512	正方形输出的快捷写法。若提供，会覆盖 width / height。
width、height	int	512	仅在未提供 size 时生效。
use_opencl	bool	false	仅 CPU 模式有效，详见下文。
show_diffusion_process	bool	false	开启后，每个 progress 事件附带一张中间过程预览图（仅在运行时支持时）。
show_diffusion_stride	int	1	每 N 步发送一次预览。仅在 show_diffusion_process 为 true 时有意义。
image	string	(可省)	Base64 编码的 PNG/JPG 字节。一旦提供，本次运行切换为 img2img。
mask	string	(可省)	Base64 编码的 PNG/JPG 蒙版字节。必须与 image 同时提供，提供时切换为 inpaint。
denoise_strength	float	0.6	img2img / inpaint 的去噪强度。
aspect_ratio	string	"1:1"	仅 SDXL NPU 模式生效。两个正整数 W:H（如 "3:4"、"16:9"）。长边为 1024，短边按比例计算后向上取整到 8 的倍数。其他模式下被忽略。详见 SDXL 宽高比。

image 与 mask 必须是编码后的图像（PNG 或 JPG），而非原始 RGB 字节。后端会自行解码并按请求尺寸内部缩放。

scheduler 取值列表

scheduler 字段接受以下字符串：

取值	UI 对应	说明
dpm	DPM++ 2M	未知值会回退到此项。
dpm_karras	DPM++ 2M + Karras	Karras 噪声调度。
dpm_sde	DPM++ 2M SDE	DPM++ 的随机（SDE）变体。
dpm_sde_karras	DPM++ 2M SDE + Karras
euler_a / eulera	Euler A	Ancestral Euler。两种写法都接受。
euler_a_karras	Euler A + Karras
euler	Euler	确定性 Euler。
euler_karras	Euler + Karras
lcm	LCM	极低步数快速生成。不支持 Karras——不要给 lcm 加 _karras 后缀。

要启用 Karras 噪声调度，在 scheduler 名称后追加 _karras（lcm 除外）。UI 上的 Karras 开关就对应这个后缀。

各模式行为差异

SD1.5 — CPU 模式

• size / width / height 可以是任意值，但必须是 8 的倍数，宽与高可以不同。
• use_opencl: true 会把 MNN 计算后端切换到 GPU 上的 OpenCL。每个分辨率首次运行会生成缓存因此较慢，之后同分辨率的运行会快很多。
• 上述所有 scheduler 取值都支持，包括各自的 _karras 变体。

SD1.5 — NPU 模式

• size（或 width × height）必须与你进入模型时选中的分辨率一致。尺寸不匹配会直接报错，而不会自动缩放。
• use_opencl 字段会被接受但不起作用。
• 上述所有 scheduler 取值都支持，包括各自的 _karras 变体。
• 当 cfg == 1.0 时，会跳过无条件 UNet 计算，单步耗时大约减半。

SDXL — NPU 模式

• 底层计算图始终在 1024 × 1024 上执行。size / width / height 会被忽略 —— 实际输出尺寸由 aspect_ratio 决定。
• aspect_ratio 默认为 "1:1"（输出 1024 × 1024）。设置为 "3:4" 或 "16:9" 等可生成非正方形图像；长边保持 1024，短边向上取整到 8 的倍数。原理详见 SDXL 宽高比。
• 其他字段与 SD1.5 NPU 模式一致。

流式响应

接口以 text/event-stream 返回，可能出现的事件类型：

event: progress
data: {"type":"progress","step":3,"total_steps":20,"image":"<base64>"}

progress 事件中的 image 字段，只在开启 show_diffusion_process 且运行时支持按当前步幅生成预览时才存在。

event: complete
data: {"type":"complete","image":"<base64>","seed":...,"width":...,"height":...,"channels":3,"generation_time_ms":...,"first_step_time_ms":...}

注意： complete 事件里的 image 是 Base64 编码的原始 RGB 像素字节（channels = 3），不是 PNG/JPG。客户端需要把它 reshape 成 (height, width, channels) 才能得到图像。

event: error
data: {"type":"error","message":"..."}

对于请求侧错误（JSON 解析失败、缺少 prompt、解码失败等），后端可能直接返回非流式的 JSON 错误体，HTTP 状态码为 400 / 500。

POST /tokenize

按模型 CLIP 的 77 token 上限统计一段提示词的 token 数。

请求：

{ "prompt": "1girl, masterpiece, ..." }

响应：

{ "count": 12, "max_length": 77 }

嵌入会展开为多个 token 并已计入 count，BOS / EOS 的 +2 也已包含在内。

示例客户端

一份完整的 Python 客户端示例（处理 SSE 流并解码原始 RGB 结果图）见 xororz/local-dream#45。