Moondream logoMoondream

Query API

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

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

Request Format

ParameterTypeRequiredDescription
image_urlstringYesBase64 encoded image with data URI prefix (e.g., "data:image/jpeg;base64,...")
questionstringYesThe natural language question to ask about the image
streambooleanNoWhether to stream the response token by token (default: false)

Response Format

For non-streaming responses:

  {
  "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:

{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

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)

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 CodeDescription
400Bad Request - Invalid parameters or image format
401Unauthorized - Invalid or missing API key
413Payload Too Large - Image size exceeds limits
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server-side issue
Error Response Format

Error responses are returned in the following format:

{
  "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