
Object detections visualized.
Usage Example
Use the Structured Outputs API for structured, validated responses.
Use the same request for faces or people. The response schema matches object detection.
from vlmrun.client import VLMRun
# Initialize the VLMRun client
client = VLMRun(api_key="<VLMRUN_API_KEY>")
# Execute object detection
response = client.agent.completions.create(
model="vlmrun-orion-1:auto",
messages=[
{"role": "user", "content": [
{"type": "text", "text": "Detect all objects in this image"},
{"type": "image_url", "image_url": {"url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.object-detection/donuts.png", "detail": "auto"}}
]},
],
)
print(response.choices[0].message.content)
from vlmrun.client import VLMRun
from pydantic import BaseModel, Field
# Define the response schema
class Detection(BaseModel):
label: str = Field(..., description="Name of the detected object")
xywh: tuple[float, float, float, float] = Field(..., description="Bounding box (x, y, width, height)")
class Detections(BaseModel):
detections: list[Detection] = Field(..., description="List of detections")
# Initialize the VLMRun client
client = VLMRun(api_key="<VLMRUN_API_KEY>")
# Execute object detection with structured output
response = client.agent.completions.create(
model="vlmrun-orion-1:auto",
messages=[
{"role": "user", "content": [
{"type": "text", "text": "Detect all objects in this image"},
{"type": "image_url", "image_url": {"url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.object-detection/donuts.png", "detail": "auto"}}
]},
],
response_format={"type": "json_schema", "schema": Detections.model_json_schema()},
)
# Validate the response
result = Detections.model_validate_json(response.choices[0].message.content)
# >>> Detections(detections=[Detection(label="donut", xywh=(...)), ...])
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: "Detect all objects in this image" },
{ type: "image_url", image_url: { url: "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.object-detection/donuts.png", 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 DetectionsSchema = z.object({
detections: z.array(z.object({
label: z.string().describe("Name of the detected object"),
xywh: z.array(z.number()).describe("Bounding box (x, y, width, height)")
})).describe("List of detections")
});
// Initialize the VLMRun client
const client = new VlmRun({
apiKey: "<VLMRUN_API_KEY>",
baseURL: "https://api.vlm.run/v1"
});
// Execute object detection with structured output
const response = await client.agent.completions.create({
model: "vlmrun-orion-1:auto",
messages: [
{
role: "user",
content: [
{ type: "text", text: "Detect all objects in this image" },
{ type: "image_url", image_url: { url: "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.object-detection/donuts.png", detail: "auto" } }
]
}
],
response_format: {
type: "json_schema",
schema: zodToJsonSchema(DetectionsSchema)
}
});
const result = DetectionsSchema.parse(JSON.parse(response.choices[0].message.content));
FAQ
What objects are supported?
What objects are supported?
Open-world (open-set) detection. There is no predefined category list. Describe the object in natural language. That includes rare items, parts of objects, and visual relations.
What format do the bounding boxes come in?
What format do the bounding boxes come in?
Normalized
xywh. Each value is between 0 and 1.| Field | Meaning |
|---|---|
x | Top-left corner, fraction of image width |
y | Top-left corner, fraction of image height |
w | Width, fraction of image width |
h | Height, fraction of image height |
What is the confidence score?
What is the confidence score?
A value between 0 and 1.

