---
title: "Image Generate"
method: POST
path: "/v1/image/generate"
tags: ["image", "image"]
---

# Image Generate

`POST /v1/image/generate`

## Request

- Base URL: `https://api.vlm.run` (the document declares no server; this is the origin it was published from)
- URL: `https://api.vlm.run/v1/image/generate`
- Auth: HTTP bearer

Generate structured prediction for the given image.

## Request body

- ImagePredictionRequest: Request to the VLM API (i.e. structured prediction).
  - `metadata` RequestMetadata: Metadata for the request. Typically captured in {"vlmrun": {"metadata": {"environment": <environment>, ...}}.
    - `environment` 'dev' | 'staging' | 'prod': The environment where the request was made.
    - `session_id` string, nullable: The session ID of the request
    - `allow_logging` boolean: Whether to enable logs for this request.
    - `allow_training` boolean: Whether the file can be used for training
    - `allow_retention` boolean: Whether to allow retention of the data
    - `extra` object: Extra metadata for the request (e.g. `dataset_id`, `subset_id`).
  - `config` GenerationConfig: Request configuration for image/document/video generation.
    - `prompt` string, nullable: Additional user instructions appended to the application or skill prompt for this request.
    - `detail` 'auto' | 'hi' | 'lo': The detail level to use for processing multimodal data.
    - `json_schema` object, nullable: The overridden JSON schema to use for the model. To be used instead of the response model.
    - `skills` AgentSkill[], nullable: List of agent skills to enable for this generation request.
      - `type` string: The type of the skill. Use 'skill_reference' for DB-stored skills referenced by id/name. Use 'inline' to provide the skill as a base64-encoded zip bundle.
      - `skill_id` string, nullable: The unique identifier of the skill — a UUID or a name string (e.g., 'pillow', 'batch-processing').
      - `skill_name` string, nullable: Human-readable skill name for lookup (e.g., 'invoice-extraction'). Alternative to skill_id. Deprecated in favour of skill_id.
      - `skill_version` union: The version of the skill — an integer (e.g. 2) or 'latest'.
        - integer
        - string
      - `version` union: DEPRECATED: Use 'skill_version' instead. The version of the skill.
        - integer
        - string
      - `name` string, nullable: Human-readable name for the inline skill (used for discovery and logging).
      - `description` string, nullable: Short description of what the inline skill does.
      - `source` InlineSkillSource: Source payload for an inline skill bundle. Follows the OpenAI inline skill format:: { "type": "base64", "media_type": "application/zip", "data": "<base64-encoded-zip>" }
        - `type` 'base64': Encoding type for the inline skill data. Currently only 'base64' is supported.
        - `media_type` string: MIME type of the skill bundle. Must be 'application/zip'.
        - `data` string, required: Base64-encoded zip bundle containing the skill files.
      - `bundle` string, nullable: DEPRECATED: Use 'source.data' instead. Base64-encoded zip bundle containing the skill files (inline skills only).
    - `gql_stmt` string, nullable: The GraphQL statement to use for the application. If provided, the response model will be generated from the GraphQL statement.
    - `max_retries` integer: The maximum number of retries to use for the application.
    - `max_tokens` integer: The maximum number of tokens to use for the application.
    - `temperature` number: The temperature to use for the application.
    - `confidence` boolean: Include confidence scores in the response (included in the `_metadata` field).
    - `grounding` boolean: Include grounding in the response (included in the `_metadata` field).
    - `keyframes` boolean: Include keyframes in the video transcription response.
    - `video_segment_duration` number, nullable: Duration in seconds for each video segment when chunking a video for transcription. Defaults to 150.0s.
    - `video_frames_per_segment` integer, nullable: Number of frames to sample per video segment for captioning. Defaults to 8.
    - `video_model` string, nullable: Model ID to use for video segment captioning (e.g. 'vlmrun-orion-1:fast'). When omitted, the server default is used.
    - `video_input_mode` 'frames' | 'native_video', nullable: How to pass video to the captioning model: 'frames' extracts N JPEG frames per segment, 'native_video' sends the mp4 clip directly via video_url for models with native video understanding. Defaults to 'native_video' for Qwen deployment models, 'frames' for others.
    - `video_transcribe_audio` boolean: When True, transcribe the audio track to align segment boundaries. When False (default), skip ASR and use fixed-duration video segments only (visual-only captioning).
    - `chat_context` string, nullable: Plain-text chat transcript (prior turns + current request) used to ground video captioning / transcription on what the user wants extracted.
    - `page_indices` integer[], nullable: 0-indexed page indices to process for document files. If None, all pages are processed.
    - `use_context_cache` boolean: Reuse cached representations of document/video content across calls. When True (default), the file is cached after the first call so repeated queries against the same file skip re-transmitting its contents. Set to False to always send the full content.
    - `service_tier` 'auto' | 'default' | 'standard' | 'flex' | 'priority', nullable: Delivery tier for the request. 'standard'/'default' uses baseline rates, 'flex' applies a 50% discount with higher latency, 'priority' applies a 1.8x premium. When omitted (or 'auto'), the server default ('standard') applies. The chosen tier drives both billing and the latency/availability SLO.
  - `id` string: Unique identifier of the request.
  - `created_at` string, date-time: Date and time when the request was created (in UTC timezone)
  - `callback_url` string, uri, nullable: The URL to call when the request is completed.
  - `images` string[], required: List of base64 encoded images or URLs to the images.
  - `model` union: The model to use for generating the response.
    - 'vlm-1' | 'vlm-1:auto' | 'vlm-1:fast' | 'vlm-1:pro'
    - string
  - `domain` union: The domain identifier (e.g. `image.caption`). Optional when a skill is provided via config.skills.
    - 'aerospace.remote-sensing' | 'document.invoice' | 'document.markdown' | 'document.receipt' | 'document.resume' | 'image.caption' | 'image.object-detection' | 'image.person-detection' | 'retail.product-catalog'
    - 'document.invoice' | 'document.markdown' | 'document.receipt' | 'document.resume' | 'document.us-drivers-license' | 'document.layout-detection' | 'construction.blueprint' | 'healthcare.patient-referral' | 'healthcare.patient-identification' | 'healthcare.physician-order' | 'healthcare.claims-processing' | 'healthcare.phi-redaction' | 'healthcare.phi-edit-replace' | 'healthcare.lab-report' | 'healthcare.prior-authorization-request' | 'healthcare.explanation-of-benefits'
    - string
  - `batch` boolean: Whether to process the image in batch mode (async).

## Response `201`

Successful Response

- PredictionResponse: Base prediction response for all API responses.
  - `usage` CreditUsageResponse: Response model for credit usage metrics.
    - `elements_processed` integer, nullable: Number of elements processed.
    - `element_type` 'image' | 'page' | 'video' | 'audio', nullable: The type of element processed (e.g. image, page, video, audio).
    - `credits_used` integer, nullable: Amount of total credits used.
    - `steps` integer, nullable: Number of steps processed, in case of agentic execution.
    - `message` string, nullable: The message from the credit usage job.
    - `duration_seconds` integer: Duration of the request in seconds.
    - `service_tier` string, nullable: Delivery tier (standard, priority, flex).
    - `mode_multiplier` number, nullable: Pricing multiplier applied to standard cost.
    - `standard_cost_dollars` number, nullable: Pre-multiplier customer cost in USD, derived from tokens and unit rates.
    - `cost_dollars` number, nullable: Effective customer cost in USD after the service-tier multiplier.
    - `savings_dollars` number, nullable: Discount in USD when using flex (standard_cost_dollars - cost_dollars).
  - `id` string: Unique identifier of the response.
  - `created_at` string, date-time: Date and time when the request was created (in UTC timezone)
  - `completed_at` string, date-time, nullable: Date and time when the response was completed (in UTC timezone)
  - `response` unknown
  - `status` 'pending' | 'enqueued' | 'running' | 'completed' | 'failed' | 'paused': The status of the job.
  - `domain` string, nullable: The domain of the prediction (e.g. document.invoice, image.caption).
  - `fallback` boolean: True when the JSON was produced by a fallback model. False when the primary model succeeded.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-19** `4a68ab36546b`: 1 info
  - added the optional property `fallback` to the response with the `201` status

[Operation history](https://skmtc.dev/vlm/apis/vlm-run-unified-server/changes/v1/image/generate/post.md)

---

[API](https://skmtc.dev/vlm/apis/vlm-run-unified-server.md) · [All operations](https://skmtc.dev/vlm/apis/vlm-run-unified-server/llms.txt) · [OpenAPI document](https://skmtc.dev/vlm/apis/vlm-run-unified-server/revisions/4a68ab36546b?raw)