VLM – Requests

ModelsDatasetsXimilar 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.

Request Endpoints

Once a task has a trained, deployed model, you run inference by submitting an async request. Requests are processed in the background by a pool of workers: you submit a request, receive an id immediately, and then poll for the result (or receive it via a webhook).

The request body follows the OpenAI chat-completions messages format, so you can send one or more images together with optional prompt instructions.

The shape of the response depends on the task mode and the trained model:

  • instruction: the rendered result template, parsed into the dataset's result_format when possible (e.g. a JSON object with your variables)
  • agentic: the assistant's turn, i.e. thoughts, tool calls with arguments and/or the final answer, so your application can execute the tools and continue the conversation
  • retrieval: the embedding vector(s) of the submitted images and text, ready to be stored in a vector index

The API stores request and response as opaque JSON; it does not validate them per mode.

Request Lifecycle

A request moves through a series of statuses. Submit returns CREATED; the result is ready once the status reaches DONE.

StatusDescription
CREATEDSubmitted and waiting in the queue to be picked up by a worker.
PENDINGReserved by a worker, about to be processed.
PROCESSINGA worker has claimed the request and the model is generating the response.
RETRYA transient failure occurred (e.g. rate limit or GPU OOM); the request will be retried automatically.
DONECompleted successfully — the response field holds the model output.
FAILEDProcessing failed after exhausting all retries.
API_LIMIT_EXCEEDEDRate limit hit or insufficient credits.
NOT_SUPPORTEDThe request or the model is not supported.

Completed requests are retained for a limited time (2 weeks by default) and then automatically cleaned up. Download or store the response if you need it long-term.

Prompt Resolution

You usually do not need to send any prompt text — the model uses the system and user prompts configured on the task. When you do want to override them for a single request, the prompt is resolved in this order of priority:

  1. system_prompt_id / user_prompt_id — a reference to a saved prompt. Highest priority.
  2. Inline text in messages — a system message and/or a user text part written directly in the request.
  3. Task default — the prompt referenced by the task. Used when neither of the above is provided.
POST/v2/request/

Submit Request

Submit a new async inference request for a trained task. Returns the created request immediately with status CREATED — poll Get Request Status or Get Request for the result.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    task_id
    Type
    string
    Description

    UUID of the VLM task to run inference on. The task must have a trained model.

  • Name
    request
    Type
    object
    Description

    The inference payload in OpenAI chat-completions format. Contains a messages array with the image(s) and any inline prompt text. Provide between 1 and 10 images per request.

Optional attributes

  • Name
    version
    Type
    integer
    Description

    Model version to use. Defaults to the task's current production_version.

  • Name
    system_prompt_id
    Type
    string
    Description

    UUID of a saved prompt to use as the system prompt for this request. Takes priority over the task's system prompt and any inline system message.

  • Name
    user_prompt_id
    Type
    string
    Description

    UUID of a saved prompt to use as the user prompt (instruction) for this request. Takes priority over the task's user prompt and any inline user text.

  • Name
    webhook
    Type
    object
    Description

    Callback target for the result, e.g. {"url": "https://...", "headers": {...}}. When set, the response is POSTed to this URL once the request is DONE.

  • Name
    priority
    Type
    integer
    Description

    Queue priority (higher is processed first). Defaults to your account priority.

Returns

  • Name
    id
    Type
    string
    Description

    UUID of the created request. Use it to poll for the result.

  • Name
    status
    Type
    string
    Description

    Current status — CREATED right after submission.

  • Name
    task_id
    Type
    string
    Description

    UUID of the task the request was submitted to.

  • Name
    version
    Type
    integer
    Description

    Model version the request will be processed with.

  • Name
    created
    Type
    string
    Description

    Timestamp when the request was created (ISO 8601 format).

  • Name
    workspace
    Type
    string
    Description

    UUID of the workspace the request belongs to.

Request

POST
/v2/request/
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -H 'Content-Type: application/json' \
     -d '{
       "task_id": "__TASK_ID__",
       "request": {
         "messages": [
           {
             "role": "user",
             "content": [
               {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
             ]
           }
         ]
       }
     }' \
     https://api.ximilar.com/vlm/v2/request/

Response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "CREATED",
  "task_id": "dbb498ba-cf24-4400-9897-d5196444a880",
  "version": 2,
  "created": "2026-01-15T09:21:04.118273Z",
  "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
}
GET/v2/request/{request_id}/status/

Get Request Status

Get only the status of a request. This is a lightweight endpoint intended for polling — it does not return the (potentially large) request and response payloads.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    request_id
    Type
    string
    Description

    UUID of the request.

Returns

  • Name
    status
    Type
    string
    Description

    Current status of the request (see Request Lifecycle).

Request

GET
/v2/request/{request_id}/status/
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/request/__REQUEST_ID__/status/

Response

{
  "status": "DONE"
}
GET/v2/request/{request_id}/

Get Request

Get the full detail of a request, including the original request payload and, once the request is DONE, the model response and token usage.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    request_id
    Type
    string
    Description

    UUID of the request.

Returns

  • Name
    id
    Type
    string
    Description

    UUID of the request.

  • Name
    status
    Type
    string
    Description

    Current status of the request.

  • Name
    task_id
    Type
    string
    Description

    UUID of the task.

  • Name
    version
    Type
    integer
    Description

    Model version used.

  • Name
    request
    Type
    object
    Description

    The original inference payload that was submitted.

  • Name
    response
    Type
    object
    Description

    The model output. null until the request is DONE (or an error object on failure).

  • Name
    usage
    Type
    object
    Description

    Token usage statistics (e.g. prompt_tokens, completion_tokens, total_tokens, processing_time). null until the request completes.

  • Name
    system_prompt_id
    Type
    string
    Description

    Saved system prompt override applied to this request, if any.

  • Name
    user_prompt_id
    Type
    string
    Description

    Saved user prompt override applied to this request, if any.

  • Name
    webhook
    Type
    object
    Description

    Webhook target the result is/was delivered to, if configured.

  • Name
    retry_count
    Type
    integer
    Description

    Number of times the request has been retried.

  • Name
    created
    Type
    string
    Description

    Timestamp when the request was created (ISO 8601 format).

  • Name
    started_at
    Type
    string
    Description

    Timestamp when a worker started processing the request.

  • Name
    completed_at
    Type
    string
    Description

    Timestamp when the request reached a terminal state.

  • Name
    workspace
    Type
    string
    Description

    UUID of the workspace the request belongs to.

Request

GET
/v2/request/{request_id}/
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/request/__REQUEST_ID__/

Response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "DONE",
  "task_id": "dbb498ba-cf24-4400-9897-d5196444a880",
  "version": 2,
  "request": {
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Describe this product and estimate its price."},
          {"type": "image_url", "image_url": {"url": "https://example.com/front.jpg"}}
        ]
      }
    ]
  },
  "response": {"description": "A wooden puzzle for kids.", "price": 8.99},
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 92,
    "total_tokens": 359,
    "processing_time": 3.33
  },
  "system_prompt_id": null,
  "user_prompt_id": null,
  "webhook": null,
  "retry_count": 0,
  "created": "2026-01-15T09:21:04.118273Z",
  "started_at": "2026-01-15T09:21:06.402551Z",
  "completed_at": "2026-01-15T09:21:09.731904Z",
  "workspace": "748e50e4-d081-4924-b9e7-f500aac6a71d"
}
GET/v2/request/

List Requests

List requests in your workspace. Returns paginated results with large payload fields omitted for performance.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

Optional attributes

  • Name
    workspace
    Type
    string
    Description

    Workspace UUID. Defaults to your default workspace.

  • Name
    status
    Type
    string
    Description

    Filter by status, e.g. CREATED, PROCESSING, DONE, FAILED.

  • Name
    task_id
    Type
    string
    Description

    Filter by task UUID.

  • Name
    page_size
    Type
    integer
    Description

    Number of results per page.

Request

GET
/v2/request/
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     'https://api.ximilar.com/vlm/v2/request/?status=DONE&task_id=__TASK_ID__'
GET/v2/request/history/

Request History

List completed (DONE) requests, including their response and usage. Uses fast cursor-based pagination — follow the next cursor returned in the response to page through results.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

Optional attributes

  • Name
    task_id
    Type
    string
    Description

    Filter history by task UUID.

  • Name
    page_size
    Type
    integer
    Description

    Number of results per page (default 20, max 100).

  • Name
    cursor
    Type
    string
    Description

    Pagination cursor returned in a previous response.

Request

GET
/v2/request/history/
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     'https://api.ximilar.com/vlm/v2/request/history/?task_id=__TASK_ID__&page_size=20'
POST/v2/request/{request_id}/resubmit/

Resubmit Request

Re-queue a request that finished in a terminal state (DONE, FAILED, API_LIMIT_EXCEEDED, or NOT_SUPPORTED). The status is reset to CREATED and the previous response, usage, and timing fields are cleared so the request is processed again.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    request_id
    Type
    string
    Description

    UUID of the request to resubmit.

Request

POST
/v2/request/{request_id}/resubmit/
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/request/__REQUEST_ID__/resubmit/
DELETE/v2/request/{request_id}/

Delete Request

Delete a request. A request that is currently PROCESSING cannot be deleted, and a DONE request can only be deleted after it has been billed.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    request_id
    Type
    string
    Description

    UUID of the request to delete.

Request

DELETE
/v2/request/{request_id}/
curl -v -XDELETE \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/vlm/v2/request/__REQUEST_ID__/

Was this page helpful?