Local Dream API Endpoint.md

Local Dream API Specification

https://github.com/xororz/local-dream
local dream 앱의 백그라운드에서 실행되는 API 서버에 대한 문서입니다.

1. Health Check

서버의 가동 상태를 확인합니다.

• URL: /health
• Method: GET
• Response:
  • 200 OK: 서버 정상 가동 중

---

2. Image Generation

이미지를 생성합니다 (Txt2Img, Img2Img, Inpaint 지원). 결과는 SSE(Server-Sent Events)를 통해 실시간으로 전달됩니다.

• URL: /generate
• Method: POST
• Content-Type: application/json

Request Body

Parameter	Type	Default	Description
prompt	String	(Required)	생성할 이미지에 대한 설명 (긍정 프롬프트)
negative_prompt	String	""	제외할 요소에 대한 설명 (부정 프롬프트)
steps	Integer	20	샘플링 단계 수
cfg	Float	7.5	프롬프트 준수 강도 (Classifier Free Guidance)
seed	Integer	(Random)	재현성을 위한 시드 값
width	Integer	512	출력 이미지 가로 크기
height	Integer	512	출력 이미지 세로 크기
scheduler	String	"dpm"	샘플러 유형 (dpm, euler_a)
denoise_strength	Float	0.6	Img2Img 시 원본 유지 강도 (0.0~1.0)
image	String	null	Img2Img용 원본 이미지 (Base64 encoded)
mask	String	null	Inpaint용 마스크 이미지 (Base64 encoded)
show_diffusion_process	Boolean	false	중간 생성 과정 이미지 전송 여부
show_diffusion_stride	Integer	1	중간 이미지 전송 간격 (Step 단위)
use_opencl	Boolean	false	MNN(CPU/GPU) 모드 시 OpenCL 가속 사용 여부

Response (Event Stream)

데이터는 text/event-stream 포맷으로 전송됩니다.

1. Event: progress
   • 생성 도중 상태를 알립니다.
   • data: {"type": "progress", "step": 5, "total_steps": 20, "image": "B64..."} (image는 설정 시에만 포함)
2. Event: complete
   • 생성이 완료되었을 때 최종 결과를 보냅니다.
   • data: {"type": "complete", "image": "B64...", "seed": 123, "width": 512, "height": 512, "generation_time_ms": 1500, ...}
3. Event: error
   • 오류 발생 시 상세 내용을 보냅니다.
   • data: {"type": "error", "message": "Reason..."}

---

3. Image Upscale

이미지를 4배로 확대합니다. 성능을 위해 바이너리 프로토콜을 사용합니다.

• URL: /upscale
• Method: POST
• Content-Type: application/octet-stream (Raw RGB Data)

Request Headers

Header	Value	Description
X-Image-Width	Integer	원본 이미지 가로 크기 (필수)
X-Image-Height	Integer	원본 이미지 세로 크기 (필수)
X-Upscaler-Path	String	사용할 업스케일 모델 파일 경로 (필수)
X-Use-OpenCL	Boolean	MNN 모델 사용 시 OpenCL 가속 여부 (true/1)

Request Body

• 원본 이미지의 Raw RGB 데이터 (바이너리).
• 크기: width * height * 3 바이트.

Response

• Content-Type: image/jpeg
• Body: 4배 확대된 결과 이미지 (JPEG 포맷).
• Custom Headers:
  • X-Output-Width: 확대된 이미지 가로 크기
  • X-Output-Height: 확대된 이미지 세로 크기
  • X-Duration-Ms: 업스케일에 소요된 시간 (ms)

---

Error Codes

Status	Type	Description
400	request_error	잘못된 파라미터나 형식 (JSON 파싱 에러 등)
500	server_error	엔진 내부 연산 오류 (NPU 드라이버 문제, 메모리 부족 등)