VLM – Tasks

Prompts Models Ximilar Platform

This page is part of the Custom Vision Language Models (VLM) API reference. See the overview for task modes, key concepts, the end-to-end workflow and the list of all endpoints.

Task Endpoints

A task defines the model you train. Its mode (instruction, agentic or retrieval) is fixed at creation and must match every connected dataset.

GET/v2/task/

Check the configuration of a task and of its datasets without starting training. Instruction and agentic tasks need a non-empty system and user prompt; every connected dataset must pass Validate Dataset. Sample counts and per-sample issues are not checked here; they are reported by the dataset and sample validate endpoints and by Train Task.

Use POST /v2/task/validate-batch/ with a body {"ids": ["__TASK_ID__", "..."]} to validate several tasks at once. The response is {"results": {"<task_id>": {...}}}.

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
task_id
Type
string
Description
UUID of the task.

Returns

Name
valid
Type
boolean
Description
true when the task and all connected datasets are configured correctly.
Name
validation_errors
Type
array
Description
Task-level problems, e.g. "Missing system prompt", "Missing user prompt".
Name
not_valid_datasets
Type
array
Description
Datasets with configuration problems, each with dataset_id, dataset_name and validation_errors.

Request

POST

/v2/task/{task_id}/validate/

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/task/__TASK_ID__/validate/

Response

{
  "valid": false,
  "validation_errors": ["Missing user prompt"],
  "not_valid_datasets": [
    {
      "dataset_id": "8797c273-b1d3-4e6f-82bb-adfb719415fe",
      "dataset_name": "Grading dataset",
      "validation_errors": ["Missing variables: explain"]
    }
  ]
}

POST/v2/task/{task_id}/train/

Train Task

Start training a new model version for the task. All samples of the connected datasets are used; samples flagged as test are held out for evaluation. Invalid samples are skipped, they do not block training.

Before the training is queued the task must pass these checks:

the task has at least one dataset and all datasets have the task's mode
instruction and agentic tasks have a non-empty system prompt and user prompt
at least 20 samples across all datasets; for retrieval tasks at least 20 anchors that have a positive (1.0000) document
the base model in training_params matches the mode (Qwen/Qwen3-VL-Embedding-2B for retrieval, a generative model otherwise)
no video or audio media is attached (media assets can be stored but not trained on yet)
no other model of the task is currently training
you have enough credits for the training operation

Training runs in the background. Poll List Models for the train_status. When auto_deploy is on, the new version becomes the production_version as soon as it is TRAINED.

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
task_id
Type
string
Description
UUID of the task to train.

Optional attributes

Name
training_provider_scope
Type
string
Description
Where the training may run: ANY (default), CLOUD_ONLY or KUBERNETES_ONLY.

Errors

Validation failures return 400 with {"detail": "VLM training data validation failed.", "validation_errors": [...]}. Each entry has error_type and reason, for example:

not_enough_samples: There are fewer than 20 samples across all datasets (found 12).
missing_system_prompt / missing_user_prompt: Task must have a non-empty system prompt.
mode_mismatch: Dataset mode 'agentic' does not match task mode 'instruction'.
invalid_config: Retrieval tasks require embedding model 'Qwen/Qwen3-VL-Embedding-2B', got 'LiquidAI/LFM2.5-VL-450M'.
unsupported_media: video and audio attachments cannot be trained yet.

Request

POST

/v2/task/{task_id}/train/

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/task/__TASK_ID__/train/

Response

{
  "id": "dbb498ba-cf24-4400-9897-d5196444a880",
  "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
}

POST/v2/task/{task_id}/set-production-version/

Set Production Version

Deploy a specific trained model version. Requests without an explicit version will use this version. The same effect can be achieved with PATCH /v2/task/{task_id}/ and {"production_version": 2}.

Required attributes

Name
Authorization
Type
string
Description
Unique API token for authentication.
Name
task_id
Type
string
Description
UUID of the task.
Name
version
Type
integer
Description
Version number of a model with train_status TRAINED.

Errors

No TRAINED model with version 3 exists for this task.

Request

POST

/v2/task/{task_id}/set-production-version/

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -H 'Content-Type: application/json' \
     -d '{"version": 2}' \
     https://api.ximilar.com/vlm/v2/task/__TASK_ID__/set-production-version/

Response

{
  "id": "dbb498ba-cf24-4400-9897-d5196444a880",
  "production_version": 2
}