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 にのみバインドされるため、別の端末からは明示的なポートフォワード無しではアクセスできません。

接続方法

PC から ADB フォワード

adb forward tcp:8081 tcp:8081
# 以降、PC 上の http://localhost:8081 でバックエンドに到達します。

Termux で端末内から

Termux 内でスクリプトを実行すれば、localhost:8081 がそのままバックエンドのアドレスになります。

エンドポイント一覧

メソッド	パス	用途
POST	/generate	生成実行。SSE でストリーミング応答
POST	/tokenize	プロンプトのトークン数を 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	true の場合、各 progress イベントに中間プレビュー画像が含まれます（ランタイムが対応する場合）。
show_diffusion_stride	int	1	N ステップごとにプレビューを送信。show_diffusion_process が true の場合のみ意味があります。
image	string	(省略可)	ソース画像の PNG/JPG バイト列 を Base64 エンコードした文字列。指定すると img2img に切り替わる。
mask	string	(省略可)	マスクの PNG/JPG バイト列の Base64。image と同時指定が必須。指定すると inpaint に切り替わる。
denoise_strength	float	0.6	img2img / inpaint のデノイズ強度。
aspect_ratio	string	"1:1"	SDXL NPU モード専用。2 つの正整数 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 に切り替わります。各解像度で初回はキャッシュ生成のために遅くなりますが、同じ解像度での 2 回目以降は大幅に高速化します。
• 上記すべての 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 ではありません。クライアント側で (height, width, channels) に reshape して画像化してください。

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

リクエスト側のエラー（JSON 解析失敗、prompt の欠落、デコード失敗など）の場合、サーバーはストリームではなく HTTP 400 / 500 の JSON エラーボディを直接返すことがあります。

POST /tokenize

モデル CLIP の 77 トークン上限に対してプロンプトのトークン数を計算します。

リクエスト：

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

応答：

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

エンベディングは複数トークンに展開され、count に反映されます。BOS / EOS の +2 も含まれます。

サンプルクライアント

SSE ストリームを処理し生 RGB の結果を画像化するリファレンス Python クライアントは xororz/local-dream#45 にあります。