/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).

Endpoint

bash

POST https://api.moondream.ai/v1/query

Request Format

Parameter	Type	Required	Description
`image_url`	string	Yes	Base64 encoded image with data URI prefix (e.g., `"data:image/jpeg;base64,..."`)
`question`	string	Yes	The natural language question to ask about the image
`stream`	boolean	No	Whether to stream the response token by token (default: `false`)

Response Format

For non-streaming responses:

json

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

For streaming responses, you'll receive a series of data events:

json

data: {"chunk": "Part of the", "completed": false, "request_id": "2025-03-25_query_123456"}data: {"chunk": " answer being", "completed": false, "request_id": "2025-03-25_query_123456"}data: {"chunk": " generated.", "completed": false, "request_id": "2025-03-25_query_123456"}data: {"completed": true, "chunk": "", "org_id": "a349504c-8006-54f3-8862-ba0c41d2b4d7", "request_id": "2025-03-25_query_123456"}

Examples

python

import moondream as mdfrom PIL import Image # Initialize with API keymodel = md.vl(api_key="your-api-key") # Load an imageimage = Image.open("path/to/image.jpg") # Ask a questionresult = 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 responsestream_result = model.query(image, "What's in this image?", stream=True)for chunk in stream_result["chunk"]:    print(chunk, end="", flush=True)

Tips for Effective Questions

Best Practices

Ask specific questions rather than general ones
One question at a time yields better results than multiple questions
For complex scenes, try to focus on particular areas or objects
If you want detailed answers, explicitly ask for details in your question

Error Handling

Common error responses:

Status Code	Description
400	Bad Request - Invalid parameters or image format
401	Unauthorized - Invalid or missing API key
413	Payload Too Large - Image size exceeds limits
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side issue

Error Response Format

Error responses are returned in the following format:

json

{"error": {  "message": "Detailed error description",  "type": "error_type",  "param": "parameter_name",  "code": "error_code"}}

Limitations

Maximum image size: 10MB
Supported image formats: JPEG, PNG, GIF (first frame only)
Maximum question length: 512 characters
Rate limits apply based on your plan