Skip to content

Commit 060b579

Browse files
stduhpfstduhpf
committed
improve docs
1 parent 752bbd4 commit 060b579

File tree

1 file changed

+65
-43
lines changed

1 file changed

+65
-43
lines changed

‎examples/server/server_doc.yaml‎

Lines changed: 65 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ info:
33
title: sd.cpp HTTP Server
44
description: |
55
API documentation for the sd.cpp HTTP server.
6-
6+
77
**Note on Model Loading:** This server allows changing loaded models dynamically via the `/generate_image` POST request by providing the `id` of the model found in the `/models` endpoint.
88
- ID `-1`: Keep current model.
99
- ID `-2`: Unload model.
@@ -35,14 +35,14 @@ paths:
3535
content:
3636
application/json:
3737
schema:
38-
$ref: '#/components/schemas/GenerationRequest'
38+
$ref: "#/components/schemas/GenerationRequest"
3939
responses:
40-
'200':
40+
"200":
4141
description: Successful generation
4242
content:
4343
application/json:
4444
schema:
45-
$ref: '#/components/schemas/GenerationResponse'
45+
$ref: "#/components/schemas/GenerationResponse"
4646

4747
/txt2img:
4848
post:
@@ -56,14 +56,14 @@ paths:
5656
content:
5757
application/json:
5858
schema:
59-
$ref: '#/components/schemas/GenerationRequest'
59+
$ref: "#/components/schemas/GenerationRequest"
6060
responses:
61-
'200':
61+
"200":
6262
description: Successful generation
6363
content:
6464
application/json:
6565
schema:
66-
$ref: '#/components/schemas/GenerationResponse'
66+
$ref: "#/components/schemas/GenerationResponse"
6767

6868
/result:
6969
get:
@@ -79,13 +79,13 @@ paths:
7979
required: true
8080
description: The ID of the generation task.
8181
responses:
82-
'200':
82+
"200":
8383
description: Task result found
8484
content:
8585
application/json:
8686
schema:
87-
$ref: '#/components/schemas/ResultResponse'
88-
'404':
87+
$ref: "#/components/schemas/ResultResponse"
88+
"404":
8989
description: Task not found
9090
content:
9191
text/plain:
@@ -100,7 +100,7 @@ paths:
100100
summary: Get Current Parameters
101101
description: Returns the current configuration of the server (last used generation params and current system context).
102102
responses:
103-
'200':
103+
"200":
104104
description: Current parameters
105105
content:
106106
application/json:
@@ -121,29 +121,29 @@ paths:
121121
summary: List all available models
122122
description: Returns lists of models, VAEs, LoRAs, embeddings, etc., available on the filesystem. Use the `id` from these lists to switch models in `/generate_image`.
123123
responses:
124-
'200':
124+
"200":
125125
description: List of assets
126126
content:
127127
application/json:
128128
schema:
129129
type: object
130130
properties:
131131
models:
132-
$ref: '#/components/schemas/ModelList'
132+
$ref: "#/components/schemas/ModelList"
133133
diffusion_models:
134-
$ref: '#/components/schemas/ModelList'
134+
$ref: "#/components/schemas/ModelList"
135135
text_encoders:
136-
$ref: '#/components/schemas/ModelList'
136+
$ref: "#/components/schemas/ModelList"
137137
vision_models:
138-
$ref: '#/components/schemas/ModelList'
138+
$ref: "#/components/schemas/ModelList"
139139
vaes:
140-
$ref: '#/components/schemas/ModelList'
140+
$ref: "#/components/schemas/ModelList"
141141
taes:
142-
$ref: '#/components/schemas/ModelList'
142+
$ref: "#/components/schemas/ModelList"
143143
control_nets:
144-
$ref: '#/components/schemas/ModelList'
144+
$ref: "#/components/schemas/ModelList"
145145
photo_makers:
146-
$ref: '#/components/schemas/ModelList'
146+
$ref: "#/components/schemas/ModelList"
147147
loras:
148148
type: array
149149
items:
@@ -164,7 +164,7 @@ paths:
164164
summary: Get currently loaded models
165165
description: Returns the filenames of the currently loaded models in memory.
166166
responses:
167-
'200':
167+
"200":
168168
description: Currently loaded models
169169
content:
170170
application/json:
@@ -192,7 +192,7 @@ paths:
192192
- Options
193193
summary: Get available schedulers
194194
responses:
195-
'200':
195+
"200":
196196
description: List of scheduler names
197197
content:
198198
application/json:
@@ -208,7 +208,7 @@ paths:
208208
deprecated: true
209209
description: Use /schedulers instead.
210210
responses:
211-
'200':
211+
"200":
212212
description: List of scheduler names
213213
content:
214214
application/json:
@@ -222,7 +222,7 @@ paths:
222222
- Options
223223
summary: Get available sampling methods
224224
responses:
225-
'200':
225+
"200":
226226
description: List of sampling methods
227227
content:
228228
application/json:
@@ -237,7 +237,7 @@ paths:
237237
summary: Get weight types
238238
description: Available quantization types (e.g., f32, f16, q4_0).
239239
responses:
240-
'200':
240+
"200":
241241
description: List of types
242242
content:
243243
application/json:
@@ -253,7 +253,7 @@ paths:
253253
deprecated: true
254254
description: Use /wtypes instead.
255255
responses:
256-
'200':
256+
"200":
257257
description: List of types
258258
content:
259259
application/json:
@@ -267,7 +267,7 @@ paths:
267267
- Options
268268
summary: Get RNG types
269269
responses:
270-
'200':
270+
"200":
271271
description: List of RNG types
272272
content:
273273
application/json:
@@ -281,7 +281,7 @@ paths:
281281
- Options
282282
summary: Get Prediction types
283283
responses:
284-
'200':
284+
"200":
285285
description: List of prediction types
286286
content:
287287
application/json:
@@ -295,21 +295,21 @@ paths:
295295
- Options
296296
summary: Get Preview methods
297297
responses:
298-
'200':
298+
"200":
299299
description: List of preview methods
300300
content:
301301
application/json:
302302
schema:
303303
type: array
304304
items: { type: string }
305-
305+
306306
/lora_apply_modes:
307307
get:
308308
tags:
309309
- Options
310310
summary: Get LoRA apply modes
311311
responses:
312-
'200':
312+
"200":
313313
description: List of apply modes
314314
content:
315315
application/json:
@@ -363,15 +363,12 @@ components:
363363
deprecated: true
364364
description: Not implemented
365365

366-
367366
GenerationResponse:
368367
type: object
369368
properties:
370369
task_id:
371370
type: string
372-
description: Task ID if processed asynchronously.
373-
status:
374-
type: string
371+
description: Task ID
375372

376373
# The complex request body parsing logic
377374
GenerationRequest:
@@ -400,14 +397,16 @@ components:
400397
type: integer
401398
format: int64
402399
default: -1
400+
description: Seed for the RNG. -1 for random seed.
403401
strength:
404402
type: number
405403
format: float
406404
description: Img2Img strength.
407405
control_strength:
408406
type: number
409407
format: float
410-
408+
description: ControlNet strength.
409+
411410
# --- Booleans ---
412411
auto_resize_ref_image:
413412
type: boolean
@@ -432,6 +431,9 @@ components:
432431
type: array
433432
items: { type: string }
434433
description: Array of base64 encoded reference images (for edit models).
434+
preview_method:
435+
type: string
436+
description: Method used for preview generation.
435437

436438
# --- Structured Parameters ---
437439
sample_params:
@@ -446,8 +448,10 @@ components:
446448
format: float
447449
scheduler:
448450
type: string
451+
description: Scheduler name. Call /schedulers endpoint for available options.
449452
sample_method:
450453
type: string
454+
description: Sampling method name. Call /sample_methods endpoint for available options.
451455
guidance:
452456
type: object
453457
properties:
@@ -457,11 +461,14 @@ components:
457461
img_cfg:
458462
type: number
459463
format: float
464+
description: Advanced option, used for editing and inpaint models
460465
distilled_guidance:
461466
type: number
462467
format: float
468+
description: Used for guidance-distilled models such as Flux.1[Dev]
463469
slg:
464470
type: object
471+
description: Skip-Layer Guidance (Advanced, can improve results on SD3.5 models)
465472
properties:
466473
layer_start:
467474
type: number
@@ -474,6 +481,7 @@ components:
474481
format: float
475482
layers:
476483
type: array
484+
description: Array of layers to skip for SLG pass
477485
items:
478486
type: integer
479487

@@ -501,7 +509,7 @@ components:
501509
- type: integer
502510
- type: string
503511
- type: array
504-
items:
512+
items:
505513
type: integer
506514

507515
pm_params:
@@ -513,14 +521,12 @@ components:
513521
format: float
514522
id_embed_path:
515523
type: string
524+
description: Path to the ID embedding file for PhotoMaker-v2. Should correspond exactly to the id_images.
516525
id_images:
517526
type: array
518527
description: Array of base64 encoded ID images for PhotoMaker.
519528
items:
520529
type: string
521-
preview_method:
522-
type: string
523-
description: Method used for preview generation.
524530

525531
# --- Context / System Parameters (Trigger Reloads) ---
526532
n_threads:
@@ -536,11 +542,12 @@ components:
536542
type: string
537543
lora_apply_mode:
538544
type: string
539-
545+
540546
vae_decode_only:
541547
type: boolean
542548
free_params_immediately:
543549
type: boolean
550+
description: Free parameters immediately after generation. Enabling it will cause the model to reload on every generation.
544551
offload_params_to_cpu:
545552
type: boolean
546553
keep_clip_on_cpu:
@@ -553,9 +560,24 @@ components:
553560
type: boolean
554561
taesd_preview:
555562
type: boolean
563+
description: Prevents TAE model from replacing VAE when decoding the final image, only uisng TAE for preview
564+
diffusion_conv_direct:
565+
type: boolean
566+
vae_conv_direct:
567+
type: boolean
568+
force_sdxl_vae_conv_scale:
569+
type: boolean
570+
chroma_use_dit_mask:
571+
type: boolean
572+
description: Better results with Chroma models when kept to true; but might cause issues on some backends
573+
chroma_use_t5_mask:
574+
type: boolean
575+
description: Should be kept to false unless you know what you are doing
556576
chroma_t5_mask_pad:
557577
type: integer
558-
578+
flow_shift:
579+
type: float
580+
559581
# --- Model Loading (Index based) ---
560582
# Index: -1 (Keep), -2 (Unload), >=0 (Load from list)
561583
model: { type: integer }
@@ -604,4 +626,4 @@ components:
604626
type:
605627
type: string
606628
deprecated: true
607-
description: Alias for wtype.
629+
description: Alias for wtype.

0 commit comments

Comments
 (0)