POST /api/v1/models/download

Request body

model : string

The model to download. Accepts model catalog identifiers (e.g., openai/gpt-oss-20b) and exact Hugging Face links (e.g., https://huggingface.co/lmstudio-community/gpt-oss-20b-GGUF)

quantization (optional) : string

Quantization level of the model to download (e.g., Q4_K_M). Only supported for Hugging Face links.

Example Request

curl http://localhost:1234/api/v1/models/download \
  -H "Authorization: Bearer $LM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ibm/granite-4-micro"
  }'

Response fields

Returns a download job status object. The response varies based on the download status.

job_id (optional) : string

Unique identifier for the download job. Absent when status is already_downloaded.

status : "downloading" | "paused" | "completed" | "failed" | "already_downloaded"

Current status of the download.

bytes_per_second (optional) : number

Current download speed in bytes per second. Present when status is downloading.

estimated_completion (optional) : string

Estimated completion time in ISO 8601 format. Present when status is downloading.

completed_at (optional) : string

Download completion time in ISO 8601 format. Present when status is completed.

total_size_bytes (optional) : number

Total size of the download in bytes. Absent when status is already_downloaded.

downloaded_bytes (optional) : number

Number of bytes downloaded so far. Absent when status is already_downloaded.

started_at (optional) : string

Download start time in ISO 8601 format. Absent when status is already_downloaded.

Response

{
  "job_id": "job_493c7c9ded",
  "status": "downloading",
  "total_size_bytes": 2279145003,
  "downloaded_bytes": 948,
  "bytes_per_second": 7834.710743801653,
  "estimated_completion": "2025-10-07T00:21:47.030Z",
  "started_at": "2025-10-03T15:33:23.496Z"
}

Download a model