Query

The /query endpoint enables you to ask natural language questions about images and receive detailed answers. This is also known as Visual Question Answering (VQA).

Example Request

Python

import moondream as md
from PIL import Image

# Initialize with API key
model = md.vl(api_key="your-api-key")

# Load an image
image = Image.open("path/to/image.jpg")

# Ask a question
result = model.query(image, "What's in this image?")
answer = result["answer"]
request_id = result["request_id"]
print(f"Answer: {answer}")
print(f"Request ID: {request_id}")

# Stream the response
stream_result = model.query(image, "What's in this image?", stream=True)
for chunk in stream_result["chunk"]:
    print(chunk, end="", flush=True)

Node.js

import { vl } from 'moondream';
import fs from 'fs';

// Initialize with API key
const model = new vl({ apiKey: "your-api-key" });

// Load an image
const image = fs.readFileSync("path/to/image.jpg");

// Ask a question
const result = await model.query({
  image: image,
  question: "What's in this image?"
});
console.log(`Answer: ${result.answer}`);
console.log(`Request ID: ${result.request_id}`);

// Stream the response
const stream = await model.query({
  image: image,
  question: "What's in this image?",
  stream: true
});
for await (const chunk of stream.answer) {
  process.stdout.write(chunk);
}

cURL

curl -X POST https://api.moondream.ai/v1/query \
  -H 'Content-Type: application/json' \
  -H 'X-Moondream-Auth: YOUR_API_KEY' \
  -d '{
    "model": "moondream3.1-9B-A2B",
    "image_url": "data:image/jpeg;base64,...",
    "question": "What is in this image?"
  }'

Example Response

{
  "request_id": "2025-03-25_query_2025-03-25-21:00:39-715d03",
  "answer": "Detailed text answer to your question..."
}

Parameters

Field	Type	Required	Description
model	string	Yes	Model ID. Supported values include moondream3.1-9B-A2B, moondream3-preview, or a saved finetuned checkpoint in {base_model}/{finetune_id}@{step} format.
image_url	string	Yes	Base64 data URL for the input image.
question	string	Yes	Question to answer about the image.
reasoning	boolean	No	Enable reasoning trace for non-streaming requests.
stream	boolean	No	Stream answer chunks as Server-Sent Events.

Best Practices

• Ask specific questions rather than general ones
• One question at a time yields better results than multiple questions
• If you want detailed answers, explicitly ask for details in your question
• Moondream can produce structured outputs. For example: "describe people in the image using JSON with keys 'hair_color', 'shirt_color', 'person_type'"

---

Learn More:

• Try the interactive playground to test queries
• Explore code examples in multiple languages