API Documentation

This document provides a detailed summary of the available API endpoints, including explanations, a complete list of supported parameters, and `curl` examples.

Note: Replace your_api_key with your actual API key and MODEL_NAME with the name of the model you want to use.

Main Docs

V1 API Endpoints

Base path: /v1

Text Generation

Parameters

Parameter	Type	Required	Description
Core Input
model	string \| null	optional	The model name to serve the request from. On a multi-model server, this routes the request to the specified served model. If null, the default served model is used.
messages	list[ChatCompletionMessageParam]	required (chat)	(chat only) The conversation as a list of message objects (role, content, plus optional tool_calls, name, etc.). Required for chat completions. Each message is rendered into the model's prompt via the chat template.
prompt	string \| list[string] \| list[int] \| list[list[int]] \| null	required (text)	(text only) The input text or token IDs to complete. Can be a single string, a batch of strings, or pre-tokenized ID lists. Required (or use prompt_embeds). Batching is capped by VLLM_MAX_COMPLETION_PROMPTS.
user	string \| null	optional	OpenAI-style end-user identifier. Ignored by vLLM — included only for API compatibility. No effect on generation or logging.
Sampling & Decoding
temperature	float \| null	optional	Controls randomness in sampling. Lower values (e.g. 0.2) make output more deterministic/focused; higher values (e.g. 1.5) increase diversity. 0.0 forces greedy decoding (picks the highest-probability token each step). Must be ≥ 0. Default: 1.0*.
top_p	float \| null	optional	Nucleus sampling. Only consider the smallest set of tokens whose cumulative probability reaches top_p. 1.0 = consider all tokens (disabled). 0.1 = only the top 10% probability mass. Must be in (0, 1]. Default: 1.0*.
top_k	int \| null	optional	Only sample from the top k highest-probability tokens at each step. 0 or -1 = disabled (consider all). Lower values = more focused. Note: vLLM applies samplers in a configurable order (see sampler_priority); OpenAI has no equivalent. Default: 0*.
min_p	float \| null	optional	Min-p sampling. Keeps only tokens whose probability is at least min_p × max_token_probability. Scales relative to the top token, so it adapts to confidence. 0.0 = disabled. Typical values 0.05–0.1. Default: 0.0*.
n	int	optional	Number of independent completions to generate for the prompt. Each counts against the engine's concurrency budget. Higher n = more GPU work. Default: 1.
seed	int \| null	optional	RNG seed for reproducible sampling. Same seed + same prompt + same params → same output (assuming deterministic execution). null = nondeterministic. Int64 range. Default: null.
presence_penalty	float \| null	optional	OpenAI-style penalty: tokens that have appeared at least once get their logits reduced. Positive values encourage new topics. Range typically [-2.0, 2.0]. Default: 0.0.
frequency_penalty	float \| null	optional	OpenAI-style penalty: penalty scales with how often a token has appeared. Positive values reduce repetition of frequent tokens. Range typically [-2.0, 2.0]. Default: 0.0.
repetition_penalty	float \| null	optional	HuggingFace-style multiplicative penalty: divides the logit of any already-seen token by this value. 1.0 = no penalty; >1.0 discourages repetition. Distinct from the OpenAI additive penalties above. Default: 1.0*.
length_penalty	float	optional	Used with use_beam_search. Exponentially scales beam scores by sequence length. >1.0 favors longer sequences; <1.0 favors shorter. 1.0 = neutral. Default: 1.0.
min_tokens	int	optional	Force the model to generate at least this many tokens before any stop string or stop_token_ids can terminate generation. EOS is still respected unless ignore_eos is set. Useful to prevent premature stopping in structured outputs. Default: 0.
stop	string \| list[string] \| null	optional	Stop strings — generation halts when any of these substrings appears in the output. The stop string itself is excluded from output unless include_stop_str_in_output is true. Default: [].
stop_token_ids	list[int] \| null	optional	Stop at these specific token IDs (more efficient than string matching). Merged with any server-configured default stop IDs (deduplicated, request values first). Default: [].
include_stop_str_in_output	bool	optional	When true, the matching stop string/stop token is included in the returned text instead of being stripped. Default: false.
ignore_eos	bool	optional	When true, the EOS (end-of-sequence) token does not terminate generation — the model keeps going until max_tokens or a stop condition. Useful for forcing a fixed output length. Default: false.
use_beam_search	bool	optional	Switch from random sampling to beam search. n becomes the beam width. Mutually exclusive with most samplers (top_p, top_k, min_p are ignored). Uses length_penalty for scoring. Default: false.
bad_words	list[string]	optional	Disallows these substrings from appearing in the output (enforced via token-level bans). Stronger than a soft penalty — the words cannot appear at all. Default: [].
allowed_token_ids	list[int] \| null	optional	Restrict generation to only these token IDs at every step (allowlist). null = no restriction. Useful for constrained vocabularies (e.g., classification over a fixed label set). Default: null.
logit_bias	dict[string, float] \| null	optional	Map of token ID (as string) → bias added to that token's logit. Positive bias increases the chance of that token; negative decreases. Range typically [-100, 100]. Default: null.
Length & Truncation
max_tokens	int \| null	optional	Maximum number of tokens to generate. Deprecated for chat in favor of max_completion_tokens. Bounded server-side by max_model_len - prompt_length. Default: null (chat) / 16 (text).
max_completion_tokens	int \| null	optional	(chat only) OpenAI's current name for the max output length. Preferred over max_tokens for chat. Takes precedence when both are set. Default: null.
truncate_prompt_tokens	int \| null	optional	Truncate the prompt to this many tokens before generation. -1 = keep all tokens (no truncation, but enables offset tracking). A positive value keeps only that many tokens (respecting truncation_side). Must be ≥ -1. Default: null.
truncation_side	"left" \| "right" \| null	optional	Controls which end of the prompt is kept when truncate_prompt_tokens is active. "right" keeps the first N tokens (drops the tail); "left" keeps the last N tokens (drops the head). null = use tokenizer default. Default: null.
echo	bool	optional	Text completion: echoes the prompt back as part of the output (prepended to generated text). Chat: prepends the last user message to the generated response if same role. Also enables prompt_logprobs implicitly if top_logprobs is set. Default: false.
Logprobs
logprobs	bool \| null (chat) / int \| null (text)	optional	Chat: boolean — whether to return logprobs at all. Pair with top_logprobs for the count. Text: integer 0–20 — number of top logprobs to return per generated token. null = disabled. Default: false (chat) / null (text).
top_logprobs	int \| null	optional	(chat only) Number of top alternative tokens (with logprobs) to return at each generated position. Requires logprobs: true. 0 = none. Max typically 20. Default: 0.
prompt_logprobs	int \| null	optional	Return logprobs for each prompt token (not just generated tokens). Integer = number of top logprobs per prompt token; -1 = all. In text completion, not allowed with stream=true (except 0). Must be ≥ 0 or exactly -1. Default: null.
logprob_token_ids	list[int] \| null	optional	Return logprobs for these specific token IDs at each generated position (in addition to the sampled token). More efficient than top_logprobs=-1 when you only need a fixed label set. Requires logprobs to be enabled. Not supported with beam search or with echo=true + max_tokens=0. Default: null.
Tokenization & Detokenization
skip_special_tokens	bool	optional	When detokenizing output back to text, strip special tokens (e.g., <\|im_start\|>, <eos>). false keeps them visible — useful for debugging token streams. Default: true.
spaces_between_special_tokens	bool	optional	Insert spaces between special tokens during detokenization for readability. false = no extra spacing. Default: true.
add_special_tokens	bool	optional	Add model-specific special tokens (e.g., BOS) to the prompt on top of what the chat template produces. For chat, the template usually handles this, so default is false. For raw text completion, default is true. Default: false (chat) / true (text).
Streaming
stream	bool \| null	optional	Return tokens incrementally via Server-Sent Events (SSE) as they're generated, rather than waiting for the full completion. Default: false.
stream_options	StreamOptions \| null	optional	Sub-object for streaming controls. Requires stream: true. Fields: include_usage (bool, default false) — emit a final chunk with token usage stats; continuous_usage_stats (bool, default false) — include running usage stats in every chunk. Default: null.
Structured Outputs
response_format	AnyResponseFormat \| null	optional	Constrains the output format. Accepted values: {"type": "text"} — no constraint; {"type": "json_object"} — output is valid JSON; {"type": "json_schema", "json_schema": {"schema": {...}}} — output conforms to a specific JSON Schema; {"type": "structural_tag", ...} — vLLM-specific; constrains content within structural tags. Internally maps to structured_outputs fields. On chat, json_schema requires a schema (or json_schema) sub-object. Default: null.
structured_outputs	StructuredOutputsParams \| null	optional	Direct, lower-level structured-output configuration. Exactly one constraint field may be set: json (str\|dict) — a JSON Schema; regex (str) — a regex the output must match; choice (list[str]) — output must be one of these exact strings; grammar (str) — a context-free grammar (Lark-style); json_object (bool) — output is any valid JSON object; structural_tag (str) — JSON-serialized structural-tag spec. Plus options: disable_any_whitespace, disable_additional_properties, whitespace_pattern. Setting more than one constraint raises a validation error. Default: null.
Reasoning / Thinking
reasoning_effort	"none" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "max" \| null	optional	(chat only) Controls how much reasoning/thinking effort reasoning models (e.g., o1-style, DeepSeek-R1) spend. Lower values = faster, fewer thinking tokens. none disables thinking. max is DeepSeek V4-specific and not part of the OpenAI spec. Also propagates enable_thinking into chat template kwargs for templates that require explicit opt-in. Default: null.
thinking_token_budget	int \| null	optional	Hard cap on the number of tokens the model may spend on internal "thinking" (reasoning) before producing the final answer. ≥0 = limit; -1 = unlimited (treated as unset). For reasoning models that expose a separate thinking channel. Default: null.
include_reasoning	bool	optional	(chat only) Whether to include the model's reasoning/thinking trace in the response (in the reasoning field of the assistant message). false returns only the final answer. Default: true.
repetition_detection	RepetitionDetectionParams \| null	optional	Early-terminates generation when repetitive N-gram patterns are detected (e.g., abcdabcdabcd...). Sub-fields: max_pattern_size (int, default 0) — largest N-gram to check, 0 = disabled; min_pattern_size (int, default 0) — smallest N-gram to check, 0 → defaults to 1, must be ≤ max_pattern_size; min_count (int, default 0) — how many times a pattern must repeat to trigger, must be ≥ 2 when max_pattern_size > 0. Default: null.
Tools (Chat Only)
tools	list[ChatCompletionToolsParam] \| null	optional	(chat only) List of tool/function definitions the model may call. Each tool has a type ("function") and a function (FunctionDefinition: name, description, parameters JSON Schema, optional strict, defer_loading). The model returns tool_calls in its response rather than (or alongside) text. Default: null.
tool_choice	"none" \| "auto" \| "required" \| ChatCompletionNamedToolChoiceParam \| null	optional	(chat only) Controls tool use: "none" — never call tools; "auto" — model decides whether to call a tool; "required" — model must call at least one tool; {"type": "function", "function": {"name": "..."}} — force a specific function. Default: "none".
parallel_tool_calls	bool \| null	optional	(chat only) Whether the model may emit multiple tool calls in a single response. Default: true.
Chat Template (Chat Only)
add_generation_prompt	bool	optional	(chat only) Append the assistant turn header to the rendered prompt so the model begins generating. false = render only the conversation context without prompting a response (useful for inspection). Cannot be combined with continue_final_message. Default: true.
continue_final_message	bool	optional	(chat only) Format the chat so the final message is left open-ended (no EOS), letting the model continue the last assistant message rather than starting a new one. Enables response prefilling. Mutually exclusive with add_generation_prompt. Default: false.
chat_template	string \| null	optional	(chat only) Override the Jinja2 chat template used to render messages into a prompt string (normally read from the tokenizer config). Per-request override; does not modify the served model. Required if the tokenizer defines no default template (since transformers v4.44). Default: null.
chat_template_kwargs	dict[string, Any] \| null	optional	(chat only) Extra variables passed into the Jinja template renderer (e.g., {"enable_thinking": true}, {"tools": [...]}). Accessible as variables inside the template. Merged with vLLM-injected kwargs (e.g., add_generation_prompt, reasoning_effort-derived enable_thinking). Default: null.
return_assistant_tokens_mask	bool	optional	(chat only) On /render endpoints, return an assistant_tokens_mask — a per-token 0/1 list marking which tokens were assistant-generated (vs. prompt). Requires the chat template to use {% generation %} tags; otherwise null. Default: false.
Response Controls
return_tokens_as_token_ids	bool \| null	optional	When returning logprobs, represent tokens as strings of the form token_id:{id} instead of decoded text. Lets you identify tokens that aren't JSON-encodable (e.g., control characters). Default: null.
return_token_ids	bool \| null	optional	Include token IDs alongside generated text in the response. In streaming mode, prompt_token_ids appears only in the first chunk; token_ids contains delta tokens per chunk. Default: null.
return_token_offsets	bool \| null	optional	Return character-level (start, end) offsets for each token relative to the source string (token_offsets field). Only honored on /v1/completions/render and /v1/chat/completions/render endpoints; ignored on regular generation. Only works with Fast (Rust-backed) tokenizers; otherwise null. Multimodal/pre-tokenized inputs always yield null. Default: false.
return_prompt_text	bool \| null	optional	(chat only) Include prompt_text in the response — the exact prompt string produced by chat templating. In streaming, sent only on the first chunk. Useful for debugging what the model actually received. Default: null.

POST /chat/completions

Handles chat completions. This endpoint takes a list of messages and returns a generated response.

1curl -X POST https://api.arliai.com/v1/chat/completions \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "model": "MODEL_NAME",
6  "messages": [
7    {"role": "system", "content": "You are a helpful assistant."},
8    {"role": "user", "content": "Hello!"}
9  ]
10}'

POST /chat/completions (with Image)

This endpoint allows you to send a text prompt along with an image for Vision Language Models (VLM). The user message content should be an array containing both the text and the image URL (base64 encoded).

1curl -X POST https://api.arliai.com/v1/chat/completions \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5 "model": "VLM_MODEL_NAME",
6 "messages": [
7   {
8     "role": "user",
9     "content": [
10       {"type": "text", "text": "What is in this image?"},
11       {
12         "type": "image_url",
13         "image_url": {
14           "url": "data:image/jpeg;base64,your_base64_encoded_image"
15         }
16       }
17     ]
18   }
19 ]
20}'

POST /completions

Handles text completions. This endpoint takes a prompt and returns a generated response.

1curl -X POST https://api.arliai.com/v1/completions \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "model": "MODEL_NAME",
6  "prompt": "Once upon a time",
7  "max_completion_tokens": 50
8}'

POST /tokenize

Tokenizes the given text.

Parameters

Parameter	Type	Required	Description
model	string	optional	The model to use for tokenization.
multi_models	array of strings	optional	A list of models to choose from.
prompt	string	optional	The prompt to tokenize.
messages	array	optional	The messages to tokenize.

1curl -X POST https://api.arliai.com/v1/tokenize \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "model": "MODEL_NAME",
6  "prompt": "Hello, world!"
7}'

Image Generation

POST /img2img

Handles image-to-image generation.

Parameters

Parameter	Type	Required	Description
sd_model_checkpoint	string	required	The name of the model checkpoint.
prompt	string	required	The text prompt.
init_images	array of strings	required	Base64-encoded initial images.
negative_prompt	string	optional	The negative prompt.
steps	integer	optional	Number of sampling steps.
sampler_name	string	optional	Sampling method.
width	integer	optional	Image width.
height	integer	optional	Image height.
clip_skip	integer	optional	Number of CLIP layers to skip.
seed	integer	optional	Random seed.
cfg_scale	number	optional	Classifier-Free Guidance scale.
stream	boolean	optional	Whether to stream the response.
batch_size	integer	optional	Number of images to generate in a batch.
denoising_strength	number	optional	Denoising strength for img2img.
mask	string	optional	Base64-encoded mask for inpainting.
mask_blur	integer	optional	Mask blur for inpainting.
inpainting_fill	integer	optional	Inpainting fill mode.
inpaint_full_res	boolean	optional	Whether to inpaint at full resolution.
inpaint_full_res_padding	integer	optional	Padding for full-resolution inpainting.
inpainting_mask_invert	integer	optional	Whether to invert the inpainting mask.
initial_noise_multiplier	number	optional	Initial noise multiplier.
detailer_enabled	boolean	optional	Enable the detailer.
detailer_prompt	string	optional	Prompt for the detailer.
detailer_negative	string	optional	Negative prompt for the detailer.
detailer_steps	integer	optional	Steps for the detailer.
detailer_strength	number	optional	Strength of the detailer.
detailer_model	string	optional	Model for the detailer.
detailer_classes	string	optional	Classes for the detailer.
detailer_conf	number	optional	Confidence for the detailer.
detailer_max	integer	optional	Max detections for the detailer.
detailer_iou	number	optional	IoU for the detailer.
detailer_padding	integer	optional	Padding for the detailer.
detailer_blur	integer	optional	Blur for the detailer.
detailer_merge	boolean	optional	Merge mode for the detailer.
schedulers_rescale_betas	boolean	optional	Rescale betas for schedulers.
schedulers_use_thresholding	boolean	optional	Use thresholding for schedulers.
schedulers_sigma	number	optional	Sigma for schedulers.
schedulers_beta_schedule	string	optional	Beta schedule for schedulers.
scheduler_eta	number	optional	ETA for schedulers.
schedulers_solver_order	integer	optional	Solver order for schedulers.
schedulers_beta_start	number	optional	Beta start for schedulers.
schedulers_beta_end	number	optional	Beta end for schedulers.
schedulers_timesteps_range	string	optional	Timesteps range for schedulers.
schedulers_shift	number	optional	Shift for schedulers.
schedulers_sigma_adjust	boolean	optional	Sigma adjustment for schedulers.
schedulers_sigma_adjust_min	number	optional	Min sigma adjustment.
schedulers_sigma_adjust_max	number	optional	Max sigma adjustment.
ip_adapter	array	optional	Image-prompt conditioning: list of {adapter, images (array of base64), scale, crop, start, end}. Requires a model with supportsIPAdapter.
control_units	array	optional	Optional ControlNet-style conditioning units applied on top of the generation (same per-unit fields as control[] on /v1/control).
init_control	array of strings	optional	Base64-encoded control input image(s) kept separate from the init image(s).

1curl -X POST https://api.arliai.com/v1/img2img \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "sd_model_checkpoint": "MODEL_NAME",
6  "init_images": ["base64_encoded_image"],
7  "prompt": "A painting of a cat in the style of Van Gogh"
8}'

POST /txt2img

Handles text-to-image generation.

Parameters

Parameter	Type	Required	Description
sd_model_checkpoint	string	required	The name of the model checkpoint.
prompt	string	required	The text prompt.
negative_prompt	string	optional	The negative prompt.
steps	integer	optional	Number of sampling steps.
sampler_name	string	optional	Sampling method.
width	integer	optional	Image width.
height	integer	optional	Image height.
clip_skip	integer	optional	Number of CLIP layers to skip.
seed	integer	optional	Random seed.
cfg_scale	number	optional	Classifier-Free Guidance scale.
stream	boolean	optional	Whether to stream the response.
batch_size	integer	optional	Number of images to generate in a batch.
hr_sampler_name	string	optional	Sampler name for high-res fix.
detailer_enabled	boolean	optional	Enable the detailer.
detailer_prompt	string	optional	Prompt for the detailer.
detailer_negative	string	optional	Negative prompt for the detailer.
detailer_steps	integer	optional	Steps for the detailer.
detailer_strength	number	optional	Strength of the detailer.
detailer_model	string	optional	Model for the detailer.
detailer_classes	string	optional	Classes for the detailer.
detailer_conf	number	optional	Confidence for the detailer.
detailer_max	integer	optional	Max detections for the detailer.
detailer_iou	number	optional	IoU for the detailer.
detailer_padding	integer	optional	Padding for the detailer.
detailer_blur	integer	optional	Blur for the detailer.
detailer_merge	boolean	optional	Merge mode for the detailer.
schedulers_rescale_betas	boolean	optional	Rescale betas for schedulers.
schedulers_use_thresholding	boolean	optional	Use thresholding for schedulers.
schedulers_sigma	number	optional	Sigma for schedulers.
schedulers_beta_schedule	string	optional	Beta schedule for schedulers.
scheduler_eta	number	optional	ETA for schedulers.
schedulers_solver_order	integer	optional	Solver order for schedulers.
schedulers_beta_start	number	optional	Beta start for schedulers.
schedulers_beta_end	number	optional	Beta end for schedulers.
schedulers_timesteps_range	string	optional	Timesteps range for schedulers.
schedulers_shift	number	optional	Shift for schedulers.
schedulers_sigma_adjust	boolean	optional	Sigma adjustment for schedulers.
schedulers_sigma_adjust_min	number	optional	Min sigma adjustment.
schedulers_sigma_adjust_max	number	optional	Max sigma adjustment.
ip_adapter	array	optional	Image-prompt conditioning: list of {adapter, images (array of base64), scale, crop, start, end}. Requires a model with supportsIPAdapter.
control_units	array	optional	Optional ControlNet-style conditioning units applied on top of the generation (same per-unit fields as control[] on /v1/control).
init_control	array of strings	optional	Base64-encoded control input image(s) kept separate from the init image(s).

1curl -X POST https://api.arliai.com/v1/txt2img \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "sd_model_checkpoint": "MODEL_NAME",
6  "prompt": "A beautiful landscape painting",
7  "steps": 20
8}'

POST /v1/control

ControlNet-guided generation: generate an image conditioned by one or more control units (ControlNet, T2I-Adapter, ControlNet-XS, ControlLLLite, Reference). Preprocessors can run server-side on the uploaded source image per unit, and optional init-image editing (input_type 1/2), IP-Adapter, and detailer refinement are supported. The response mirrors the other generation endpoints: images (base64 outputs), processed (preprocessed control maps), and info.

Parameters

Parameter	Type	Required	Description
sd_model_checkpoint	string	required	The name of the model checkpoint (must support ControlNet generation).
prompt	string	required	The text prompt.
negative_prompt	string	optional	The negative prompt.
Control Units
control	array	required	List of control units. At least one enabled unit with an image is required. See control[] fields below.
unit_type	string	optional	Control unit family used by units that don't set their own: 'controlnet', 't2i adapter', 'xs', 'lite', or 'reference'. Default: 'controlnet'.
control[].unit_type	string	optional	Per-unit type override: 'controlnet', 't2i adapter', 'xs', 'lite', or 'reference'. Defaults to the request-level unit_type.
control[].process	string	optional	Preprocessor to run on the unit image (e.g. "Canny", "OpenPose", "Depth Anything"). Empty/None uses the image as-is. List via GET /v1/preprocessors.
control[].model	string	optional	Control model file name for the unit type (e.g. "Canny XL", "OpenPose XL"). List via GET /v1/control-models.
control[].image	string	optional	Base64-encoded source image for the unit. When a process is set, the server preprocesses it once; otherwise it is used as the control map directly.
control[].override	string	optional	Base64-encoded pre-computed control map that bypasses the preprocessor. Takes priority over image.
control[].strength	number	optional	How strongly the control model influences generation (0.0-2.0). Default 1.0.
control[].start	number	optional	Step fraction at which control begins (0.0-1.0). Default 0.0.
control[].end	number	optional	Step fraction at which control ends (0.0-1.0). Default 1.0.
control[].mode	string	optional	Control mode for Union/ProMax models. List valid modes via GET /v1/control-modes.
control[].guess	boolean	optional	Guess mode: remove the need for a prompt (ControlNet only).
control[].factor	number	optional	Conditioning scale factor (T2I-Adapter only). Default 1.0.
control[].attention	string	optional	Attention mechanism: 'Attention', 'Adain', or 'Attention Adain' (Reference units).
control[].fidelity	number	optional	Style fidelity 0.0-1.0 (Reference units). Default 0.5.
control[].query_weight	number	optional	Attention query weight (Reference units). Default 1.0.
control[].adain_weight	number	optional	AdaIN weight (Reference units). Default 1.0.
control[].process_params	object	optional	Per-unit preprocessor parameter overrides, e.g. {"low_threshold": 50, "high_threshold": 150} for Canny.
Generation
sampler_name	string	optional	Sampling method.
steps	integer	optional	Number of sampling steps (max 40).
seed	integer	optional	Random seed (-1 = random).
cfg_scale	number	optional	Classifier-Free Guidance scale.
batch_size	integer	optional	Number of images to generate in a batch.
Init Image Editing
input_type	integer	optional	0 = control only, 1 = init image same as the first control image, 2 = separate init image. Default 0.
init_control	array of strings	optional	Base64-encoded init image(s) when input_type is 1 or 2, carried in the only base64 init channel the API accepts.
inits	array of strings	optional	Base64-encoded init image(s) (low-level alias).
mask	string	optional	Base64-encoded mask for inpaint-style edits.
denoising_strength	number	optional	Denoising strength when editing an init image.
Size
width_before	integer	optional	Initial/control image resolution width. Defaults to the control image size.
height_before	integer	optional	Initial/control image resolution height. Defaults to the control image size.
width_after	integer	optional	Post-generation resolution width.
height_after	integer	optional	Post-generation resolution height.
width_mask	integer	optional	Mask resolution width.
height_mask	integer	optional	Mask resolution height.
IP-Adapter
ip_adapter	array	optional	Image-prompt conditioning: list of {adapter, images (array of base64), scale, crop, start, end}. Requires supportIpAdapter model.
Detailer
detailer_enabled	boolean	optional	Enable the face/detailer refinement pass.
detailer_prompt	string	optional	Prompt for the detailer.
detailer_negative	string	optional	Negative prompt for the detailer.
detailer_steps	integer	optional	Steps for the detailer.
detailer_strength	number	optional	Strength of the detailer.
detailer_model / detailer_models	string \| array	optional	Detailer model name(s) (override_settings).
detailer_conf / detailer_iou	number	optional	Detailer detection confidence / IoU thresholds (override_settings).
detailer_max / detailer_min_size / detailer_max_size	integer	optional	Detailer bbox size limits (override_settings).
detailer_padding / detailer_blur	integer	optional	Detailer face padding / blur (override_settings).
detailer_merge / detailer_sigma_adjust / detailer_sigma_adjust_max	boolean \| number	optional	Detailer merge mode and sigma adjustment (override_settings).
Schedulers
schedulers_rescale_betas	boolean	optional	Rescale betas for schedulers.
schedulers_use_thresholding	boolean	optional	Use thresholding for schedulers.
schedulers_sigma	number	optional	Sigma for schedulers.
schedulers_beta_schedule	string	optional	Beta schedule for schedulers.
scheduler_eta	number	optional	ETA for schedulers.
schedulers_solver_order	integer	optional	Solver order for schedulers.
schedulers_use_loworder	boolean	optional	Use low-order solver.
schedulers_prediction_type	string	optional	Prediction type for schedulers.
schedulers_timestep_spacing	string	optional	Timestep spacing for schedulers.

1curl -X POST https://api.arliai.com/v1/control \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "sd_model_checkpoint": "MODEL_NAME",
6  "prompt": "a person standing in front of an ancient castle, dramatic lighting",
7  "negative_prompt": "blurry, low quality",
8  "steps": 20,
9  "seed": -1,
10  "cfg_scale": 6.0,
11  "unit_type": "controlnet",
12  "control": [
13    {
14      "unit_type": "controlnet",
15      "process": "Canny",
16      "model": "Canny XL",
17      "image": "base64_encoded_control_image",
18      "strength": 1.0,
19      "start": 0.0,
20      "end": 1.0,
21      "process_params": { "low_threshold": 100, "high_threshold": 200 }
22    }
23  ],
24  "input_type": 0,
25  "width_before": 1024,
26  "height_before": 1024
27}'

POST /v1/preprocess

Run a single control preprocessor (e.g. Canny, OpenPose, Depth Anything) on a raw image and return the resulting control map. Use this to prepare control maps before calling /v1/control with the map as a unit image, or to preview what a preprocessor produces.

Parameters

Parameter	Type	Required	Description
model	string	required	Preprocessor name (e.g. "Canny", "OpenPose", "Depth Anything", "MLSD"). List available names via GET /v1/preprocessors.
image	string	required	Base64-encoded input image to preprocess.
params	object	optional	Preprocessor parameter overrides, e.g. {"low_threshold": 50, "high_threshold": 150} for Canny. Keys must match the preprocessor config.

1curl -X POST https://api.arliai.com/v1/preprocess \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "model": "Canny",
6  "image": "base64_encoded_image",
7  "params": { "low_threshold": 100, "high_threshold": 200 }
8}'

POST /upscale-img

Upscales a single image.

Parameters

Parameter	Type	Required	Description
image	string	required	The base64-encoded image to upscale.
upscaler_1	string	optional	The name of the upscaler to use.
resize_mode	integer	optional	The resize mode.
upscaling_resize	number	optional	The factor by which to resize the image.

1curl -X POST https://api.arliai.com/v1/upscale-img \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "image": "base64_encoded_image",
6  "upscaler_1": "Lanczos"
7}'

POST /caption

Generates a descriptive prompt (OpenCLIP/BLIP) from an image.

Parameters

Parameter	Type	Required	Description
image	string	required	The base64-encoded image to generate a caption from.
model	string	required	The caption model to use (available via GET /caption/models).
mode	string	optional	Caption mode: 'best', 'fast', 'classic', 'caption', or 'negative'.
analyze	boolean	optional	When true, also returns medium, artist, movement, trending, and flavor.

1curl -X POST https://api.arliai.com/v1/caption \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "model": "MODEL_NAME",
6  "mode": "best",
7  "image": "base64_encoded_image"
8}'

POST /tagger

Generates booru-style tags (WaifuDiffusion/DeepBooru) for an image.

Parameters

Parameter	Type	Required	Description
image	string	required	The base64-encoded image to tag.
model	string	required	The tagger model to use (available via GET /tagger/models).
threshold	number	optional	Minimum general confidence to include a tag (default 0.50).
character_threshold	number	optional	Minimum character confidence to include a tag (default 0.85).
max_tags	integer	optional	Maximum number of tags to return (default 74).
include_rating	boolean	optional	Include rating tags (general, sensitive, questionable, explicit).
sort_alpha	boolean	optional	Sort tags alphabetically instead of by confidence.
use_spaces	boolean	optional	Use spaces instead of underscores between words.
escape_brackets	boolean	optional	Escape brackets so tags are prompt-safe (default true).
exclude_tags	string	optional	Comma-separated tags to always exclude.
show_scores	boolean	optional	Include per-tag confidence scores in the response.

1curl -X POST https://api.arliai.com/v1/tagger \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "model": "MODEL_NAME",
6  "image": "base64_encoded_image"
7}'

Model Information

GET /models/textgen-models

Retrieves available text generation models. No parameters.

1curl -X GET https://api.arliai.com/v1/models/textgen-models \
2-H "Authorization: Bearer your_api_key"

GET /models/image-models

Retrieves available image generation models. No parameters.

1curl -X GET https://api.arliai.com/v1/models/image-models \
2-H "Authorization: Bearer your_api_key"

GET /upscalers

Retrieves available upscalers. No parameters.

1curl -X GET https://api.arliai.com/v1/upscalers \
2-H "Authorization: Bearer your_api_key"

GET /caption/models

Retrieves the caption models available to your account. No parameters.

1curl -X GET https://api.arliai.com/v1/caption/models \
2-H "Authorization: Bearer your_api_key"

GET /tagger/models

Retrieves the tagger models available to your account. No parameters.

1curl -X GET https://api.arliai.com/v1/tagger/models \
2-H "Authorization: Bearer your_api_key"

GET /img-options

Retrieves image generation options. No parameters.

1curl -X GET https://api.arliai.com/v1/img-options \
2-H "Authorization: Bearer your_api_key"

GET /img-samplers

Retrieves available image samplers. No parameters.

1curl -X GET https://api.arliai.com/v1/img-samplers \
2-H "Authorization: Bearer your_api_key"

GET /v1/ip-adapters

Lists IP-Adapter models available for the selected checkpoint. Pass the model via the model query parameter to resolve availability for the requested architecture; without it the server falls back to its loaded checkpoint.

1curl -X GET "https://api.arliai.com/v1/ip-adapters?model=MODEL_NAME" \
2-H "Authorization: Bearer your_api_key"

GET /v1/control-models

Lists control models for a control unit type. Query parameters: model (selected checkpoint; optional — defaults to the server's loaded checkpoint) and unit_type (controlnet, t2i adapter, xs, lite, or reference).

1curl -X GET "https://api.arliai.com/v1/control-models?model=MODEL_NAME&unit_type=controlnet" \
2-H "Authorization: Bearer your_api_key"

GET /v1/preprocessors

Lists available control preprocessors (name, group, and their configurable parameters). Optionally scoped to the selected checkpoint via ?model=.

1curl -X GET "https://api.arliai.com/v1/preprocessors?model=MODEL_NAME" \
2-H "Authorization: Bearer your_api_key"

GET /v1/control-modes

Lists the control modes (Union/ProMax predefines) available for the selected checkpoint via ?model=. Returns a map of control model name to available modes.

1curl -X GET "https://api.arliai.com/v1/control-modes?model=MODEL_NAME" \
2-H "Authorization: Bearer your_api_key"

GET /parallel-requests

Retrieves parallel request limits. No parameters.

1curl -X GET https://api.arliai.com/v1/parallel-requests \
2-H "Authorization: Bearer your_api_key"

Model Status & Performance

Note: These endpoints are public and do not require an API key. They are intended for live status / monitoring and may be polled by any client. Use judiciously — avoid hammering them at high frequency.

GET /model/all

Returns the full list of available text-generation models, each annotated with a live status (availability) boolean plus cached performance and usage statistics. Use the status field to check whether a model is currently online before sending requests.

1curl -X GET https://api.arliai.com/model/all

Response Example

1[
2  {
3    "name": "Gemma-4-31B-Lilith-v1.0",
4    "reasoning": true,
5    "vlm": true,
6    "systemPrompt": "You are an intelligent assistant.",
7    "promptFormat": "Gemma4",
8    "quant": "r64",
9    "engine": "vllm",
10    "parameters": "31B",
11    "creationMethod": "LoRA Finetune",
12    "contextSize": "262144",
13    "modelLink": "https://huggingface.co/darthcrawl/Lilith-31B-v1.0",
14    "modelRecommendation": "Creative model",
15    "modelSize": "Gemma-4-31B - LoRA",
16    "modelType": "Gemma31B",
17    "requestsPerDay": "220",
18    "requestsPerWeek": "859",
19    "requestTokensPerDay": "724792",
20    "responseTokensPerDay": "6482",
21    "requestTokensPerWeek": "4929074",
22    "responseTokensPerWeek": "113803",
23    "hourlyTokenUsage": { "2026-07-31T16": 209353, "2026-07-31T17": 32663 },
24    "addedAt": "2026-07-25T22:31:08.838Z",
25    "avgResponseTime": 8218,
26    "avgTimeToFirstToken": 4743,
27    "avgPreprocessingTokensPerSecond": 1193.64,
28    "avgGenerationTokensPerSecond": 20.9,
29    "status": true
30  }
31  // ... one object per model
32]

Parameters

Parameter	Type	Required	Description
Identity
name	string	always	The model identifier to pass as the "model" field in generation requests.
status	boolean	always	Live availability. true if at least one healthy server currently serves this model type; false otherwise. Check this before sending requests to avoid errors.
reasoning	boolean	always	Whether the model supports reasoning/thinking tokens.
vlm	boolean	always	Whether the model accepts image inputs (Vision Language Model).
contextSize	string	always	Maximum context window in tokens.
parameters	string	always	Parameter count (e.g. "31B").
quant	string	always	Quantization format (e.g. "r64", "INT8", "FP8").
engine	string	always	Inference engine (e.g. "vllm").
promptFormat	string	always	Chat template / prompt format name used by the model.
creationMethod	string	always	How the model was created (e.g. "FFT", "LoRA Finetune").
modelType	string	always	Internal type grouping shared servers (e.g. "Gemma31B"). Multiple models sharing a type share one health status.
modelSize	string	always	Base group + variant. The portion before " - " is the base model used as the busyness key.
modelRecommendation	string	always	Short human-readable description / category.
systemPrompt	string	always	Default system prompt applied when none is provided.
modelLink	string	always	Source HuggingFace link.
addedAt	string (ISO date)	always	When the model was added to the platform.
Performance (24h median, per base model)
avgResponseTime	number \| null	optional	Median total response time in ms over the last 24h (base-model aggregate). null if insufficient recent data.
avgTimeToFirstToken	number \| null	optional	Median time-to-first-token in ms — measured until the first generated token of any kind (content or reasoning) is received.
avgPreprocessingTokensPerSecond	number \| null	optional	Median prefill/prompt-processing speed = requestLength / TTFT (tokens/s).
avgGenerationTokensPerSecond	number \| null	optional	Median generation speed = responseLength / generationTime (tokens/s).
Usage (cached)
requestsPerDay	string	always	Request count in the last 24h.
requestsPerWeek	string	always	Request count in the last 7 days.
requestTokensPerDay	string	always	Prompt tokens processed in the last 24h.
responseTokensPerDay	string	always	Generated tokens in the last 24h.
requestTokensPerWeek	string	always	Prompt tokens processed in the last 7 days.
responseTokensPerWeek	string	always	Generated tokens in the last 7 days.
hourlyTokenUsage	object	always	Map of ISO hour key (e.g. "2026-07-31T16") to total tokens processed that hour. Covers a rolling 48h window, zero-filled for hours with no usage.

GET /model/busyness/live

Returns the current live server busyness percentage for every base model group, keyed by base model name. Busyness is the higher of request- and token-based load against configured capacity. A value of 0 means the model currently has no in-flight traffic. Poll this to pick the least busy model or to display real-time load.

1curl -X GET https://api.arliai.com/model/busyness/live

Response Example

1{
2  "GLM-4.6-Derestricted": 12.5,
3  "Gemma-4-31B": 37.5,
4  "DeepSeek-V4-Flash-0731": 25,
5  "GLM-4.7": 6.25,
6  "Qwen3.5-27B-Derestricted": 6.25
7}

SD API V1 Endpoints

Base path: /sdapi/v1

The endpoints under /sdapi/v1 are designed for compatibility with the Stable Diffusion API and share the same parameters as their /v1 counterparts.

POST /sdapi/v1/img2img

See /v1/img2img for parameters.

1curl -X POST https://api.arliai.com/sdapi/v1/img2img \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "init_images": ["base64_encoded_image"],
6  "prompt": "A futuristic city"
7}'

POST /sdapi/v1/txt2img

See /v1/txt2img for parameters.

1curl -X POST https://api.arliai.com/sdapi/v1/txt2img \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "prompt": "A majestic lion in the savanna"
6}'

POST /sdapi/v1/control

ControlNet-guided generation in the SD-API style: the control array carries preprocessor/model/image pairs per unit, and the response includes processed (preprocessed control maps) alongside images. Equivalent to POST /v1/control.

1curl -X POST https://api.arliai.com/sdapi/v1/control \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "prompt": "a person standing in front of an ancient castle",
6  "unit_type": "controlnet",
7  "control": [
8    {
9      "unit_type": "controlnet",
10      "process": "OpenPose",
11      "model": "OpenPose XL",
12      "image": "base64_encoded_control_image",
13      "strength": 0.9
14    }
15  ]
16}'

POST /sdapi/v1/preprocess

Run a single control preprocessor on an image and return the processed control map. Equivalent to POST /v1/preprocess.

1curl -X POST https://api.arliai.com/sdapi/v1/preprocess \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "model": "Canny",
6  "image": "base64_encoded_image",
7  "params": { "low_threshold": 100, "high_threshold": 200 }
8}'

POST /sdapi/v1/extra-single-image

See /v1/upscale-img for parameters.

1curl -X POST https://api.arliai.com/sdapi/v1/extra-single-image \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer your_api_key" \
4-d '{
5  "image": "base64_encoded_image",
6  "upscaler_1": "R-ESRGAN 4x+"
7}'

GET /sdapi/v1/sd-models

Retrieves available image models.

1curl -X GET https://api.arliai.com/sdapi/v1/sd-models \
2-H "Authorization: Bearer your_api_key"

GET /sdapi/v1/upscalers

Retrieves available upscalers.

1curl -X GET https://api.arliai.com/sdapi/v1/upscalers \
2-H "Authorization: Bearer your_api_key"

GET /sdapi/v1/options

Retrieves image generation options.

1curl -X GET https://api.arliai.com/sdapi/v1/options \
2-H "Authorization: Bearer your_api_key"

GET /sdapi/v1/samplers

Retrieves available image samplers.

1curl -X GET https://api.arliai.com/sdapi/v1/samplers \
2-H "Authorization: Bearer your_api_key"

GET /sdapi/v1/ip-adapters

Lists IP-Adapter models, optionally scoped to the selected checkpoint via ?model=. Equivalent to GET /v1/ip-adapters.

1curl -X GET "https://api.arliai.com/sdapi/v1/ip-adapters?model=MODEL_NAME" \
2-H "Authorization: Bearer your_api_key"

GET /sdapi/v1/control-models

Lists control models for a control unit type, optionally scoped to the selected checkpoint (?model= and ?unit_type=). Equivalent to GET /v1/control-models.

1curl -X GET "https://api.arliai.com/sdapi/v1/control-models?model=MODEL_NAME&unit_type=controlnet" \
2-H "Authorization: Bearer your_api_key"

GET /sdapi/v1/preprocessors

Lists available control preprocessors with their parameters, optionally scoped via ?model=. Equivalent to GET /v1/preprocessors.

1curl -X GET "https://api.arliai.com/sdapi/v1/preprocessors?model=MODEL_NAME" \
2-H "Authorization: Bearer your_api_key"

GET /sdapi/v1/control-modes

Lists control modes (Union/ProMax predefines) for the selected checkpoint via ?model=. Equivalent to GET /v1/control-modes.

1curl -X GET "https://api.arliai.com/sdapi/v1/control-modes?model=MODEL_NAME" \
2-H "Authorization: Bearer your_api_key"