Start a model download

POST /v1/models/download

Starts a background download job on the service host and returns 202 Accepted, not a ready model. Downloads consume network bandwidth and disk space. Built-in EdgeSpeak/Skylark is already available and has no download, load or unload lifecycle. Poll GET /v1/models/downloads before loading.

Guide and examplesModels and service All endpoints

Request body

application/jsonRequired

modelstringRequiredCatalog model ID.

Responses

202The download job was accepted. total_bytes: 0 can mean the total is not known yet.

modelstring

statestringdownloading | completed | failed | cancelled

bytes_downloadedinteger

total_bytesinteger0 can mean the total is not known yet.

errorstring | null

{
  "model": "Qwen/Qwen3.5-4B",
  "state": "downloading",
  "bytes_downloaded": 0,
  "total_bytes": 0,
  "error": null
}

400Invalid request. Fix the request before retrying; use error.code for program logic and error.param to locate the input.

401Invalid or missing API key.

403Host or origin is not allowed, or the license was rejected. Inspect error.code to tell them apart.

503A required local model is still being prepared (model_downloading) or the service is busy (service_busy). Honor Retry-After when present.