
Segmented car mask.
Usage Example
Use the Structured Outputs API for structured, validated responses.
from vlmrun.client import VLMRun
# Initialize the VLMRun client
client = VLMRun(api_key="<VLMRUN_API_KEY>")
# Segment objects in the image
response = client.agent.completions.create(
model="vlmrun-orion-1:auto",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Segment all the cars in this image"},
{"type": "image_url", "image_url": {"url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.object-detection/nascar.jpg", "detail": "auto"}}
]
}
],
)
print(response.choices[0].message.content)
from vlmrun.client import VLMRun
from pydantic import BaseModel, Field
# Define the response schema
class SegmentationMask(BaseModel):
label: str = Field(..., description="Name of the segmented object")
mask_url: str = Field(..., description="Pre-signed URL to the PNG mask")
class Segmentations(BaseModel):
segmentations: list[SegmentationMask] = Field(..., description="List of segmentations")
# Initialize the VLMRun client
client = VLMRun(api_key="<VLMRUN_API_KEY>")
# Segment objects with structured output
response = client.agent.completions.create(
model="vlmrun-orion-1:auto",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Segment all the cars in this image"},
{"type": "image_url", "image_url": {"url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.object-detection/nascar.jpg", "detail": "auto"}}
]
}
],
response_format={"type": "json_schema", "schema": Segmentations.model_json_schema()},
)
# Validate the response
result = Segmentations.model_validate_json(response.choices[0].message.content)
# >>> Segmentations(segmentations=[SegmentationMask(label="car", mask_url="https://..."), ...])
import { VlmRun } from "vlmrun";
const client = new VlmRun({
apiKey: "<VLMRUN_API_KEY>",
baseURL: "https://api.vlm.run/v1"
});
const response = await client.agent.completions.create({
model: "vlmrun-orion-1:auto",
messages: [
{
role: "user",
content: [
{ type: "text", text: "Segment all the cars in this image" },
{ type: "image_url", image_url: { url: "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.object-detection/nascar.jpg", detail: "auto" } }
]
}
]
});
console.log(response.choices[0].message.content);
import { VlmRun } from "vlmrun";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";
// Define the response schema with Zod
const SegmentationsSchema = z.object({
segmentations: z.array(z.object({
label: z.string().describe("Name of the segmented object"),
mask_url: z.string().describe("Pre-signed URL to the PNG mask")
})).describe("List of segmentations")
});
// Initialize the VLMRun client
const client = new VlmRun({
apiKey: "<VLMRUN_API_KEY>",
baseURL: "https://api.vlm.run/v1"
});
// Segment objects with structured output
const response = await client.agent.completions.create({
model: "vlmrun-orion-1:auto",
messages: [
{
role: "user",
content: [
{ type: "text", text: "Segment all the cars in this image" },
{ type: "image_url", image_url: { url: "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.object-detection/nascar.jpg", detail: "auto" } }
]
}
],
response_format: {
type: "json_schema",
schema: zodToJsonSchema(SegmentationsSchema)
}
});
const result = SegmentationsSchema.parse(JSON.parse(response.choices[0].message.content));
FAQ
Segmentation types
Segmentation types
- Instance: one unique mask per object
- Semantic: a category for each pixel
- Panoptic: instance and semantic together
Returned masks
Returned masks
The response is a list of objects. Each object has a PNG mask at a pre-signed URL.
Categories
Categories
Name the objects in natural language. Example: “segment the writing-related items in this image.”Common objects
Specialized categories
| Category | Classes |
|---|---|
| People | person, face, hand, foot |
| Vehicles | car, truck, bus, motorcycle, bicycle |
| Animals | dog, cat, bird, horse, cow, sheep |
| Furniture | chair, table, bed, sofa, desk |
| Electronics | laptop, phone, tv, keyboard, mouse |
| Category | Classes |
|---|---|
| Medical | organ, tissue, lesion, bone |
| Nature | tree, grass, sky, water, mountain |
| Indoor | wall, floor, ceiling, door, window |
| Outdoor | road, sidewalk, building, sign, traffic_light |
Mask encodings
Mask encodings
PNG masks are binary or grayscale. Each pixel value is a segment ID.JSON polygons and COCO are coming soon.

