Moondream Python Client Library

Official Python client library for Moondream, a fast multi-function VLM. This client can target Moondream Cloud or run locally via Photon — on NVIDIA GPUs (Linux x86_64 / aarch64 or Windows) or Apple Silicon Macs.

Capabilities

Moondream goes beyond the typical VLM "query" ability to include more visual functions:

Try it out on Moondream's playground.

Photon Models

Photon local inference includes all models bundled with Kestrel 0.5:

Use md.photon_models() to inspect the exact registered identifiers in the installed release. The returned client reports model_id, tasks, and supports(task) without requiring a Kestrel import. Existing md.vl(local=True, ...) calls remain supported and delegate to md.photon(...).

Installation

pip install moondream

Quick Start

Choose how you want to run Moondream:

1. Moondream Cloud — Get an API key from the cloud console
2. Moondream Photon — High-performance local inference engine on NVIDIA GPUs (Linux / Windows) or Apple Silicon Macs (macOS 13+). Base models run locally without an API key; an API key is only needed for finetuned models.

import moondream as md
from PIL import Image

# Initialize with Moondream Cloud
model = md.vl(api_key="<your-api-key>")

# Or initialize Photon local inference (NVIDIA GPU or Apple Silicon)
model = md.photon()

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

# Generate a caption
caption = model.caption(image)["caption"]
print("Caption:", caption)

# Ask a question
answer = model.query(image, "What's in this image?")["answer"]
print("Answer:", answer)

# Stream the response
for chunk in model.caption(image, stream=True)["caption"]:
    print(chunk, end="", flush=True)

# Multi-turn chat accepts OpenAI-style messages
chat = model.chat([
    {"role": "user", "content": "My name is Alice."},
    {"role": "assistant", "content": "Nice to meet you, Alice!"},
    {"role": "user", "content": "What is my name?"},
])
print(chat["message"]["content"])

API Reference

Constructor

model = md.vl(api_key="<your-api-key>")                        # Cloud
model = md.photon()                                            # Photon with Moondream 3
model = md.vl(api_key="<your-api-key>", model="moondream3-preview/ft_id@step")  # Finetune
qwen = md.photon("Qwen/Qwen3.5-4B")
gemma = md.photon("google/gemma-4-E2B-it")

Photon clients share matching local engines. Call model.close() when an application is finished with a client, or use with md.photon() as model: for deterministic GPU and worker cleanup.

Methods

caption(image, length="normal", stream=False)

Generate a caption for an image.

Parameters:

• image — Image.Image or EncodedImage
• length — "normal", "short", or "long" (default: "normal")
• stream — bool (default: False)

Returns: CaptionOutput — {"caption": str | Generator}

caption = model.caption(image, length="short")["caption"]

# With streaming
for chunk in model.caption(image, stream=True)["caption"]:
    print(chunk, end="", flush=True)

query(image, question, stream=False, spatial_refs=None)

Ask a question about an image.

Parameters:

• image — Image.Image or EncodedImage
• question — str
• stream — bool (default: False)
• spatial_refs — optional point or box hints, normalized to 0-1

Returns: QueryOutput — {"answer": str | Generator}

answer = model.query(image, "What's in this image?")["answer"]

# With streaming
for chunk in model.query(image, "What's in this image?", stream=True)["answer"]:
    print(chunk, end="", flush=True)

chat(messages, stream=False, reasoning=None)

Continue an OpenAI-style multi-turn conversation. Message content can be text or a list of text and base64 image_url parts. When reasoning is omitted, the selected model or Cloud service supplies its default.

result = model.chat([
    {"role": "user", "content": "Remember that my favorite color is green."},
    {"role": "assistant", "content": "Got it."},
    {"role": "user", "content": "What is my favorite color?"},
])
print(result["message"]["content"])

for chunk in model.chat(
    [{"role": "user", "content": "Write a short poem about the moon."}],
    stream=True,
)["message"]:
    print(chunk, end="", flush=True)

detect(image, object)

Detect specific objects in an image.

Parameters:

• image — Image.Image or EncodedImage
• object — str

Returns: DetectOutput — {"objects": List[Region]}

objects = model.detect(image, "car")["objects"]

point(image, object, spatial_refs=None)

Get coordinates of specific objects in an image.

Parameters:

• image — Image.Image or EncodedImage
• object — str
• spatial_refs — optional point or box hints, normalized to 0-1

Returns: PointOutput — {"points": List[Point]}

points = model.point(image, "person")["points"]

segment(image, object, spatial_refs=None, stream=False)

Segment an object from an image and return an SVG path.

Parameters:

• image — Image.Image or EncodedImage
• object — str
• spatial_refs — List[[x, y] | [x1, y1, x2, y2]] — optional spatial hints (normalized 0-1)
• stream — bool (default: False)

Returns:

• Non-streaming: SegmentOutput — {"path": str, "bbox": Region}
• Streaming: Generator yielding update dicts

result = model.segment(image, "cat")
svg_path = result["path"]
bbox = result["bbox"]  # {"x_min": ..., "y_min": ..., "x_max": ..., "y_max": ...}

# With spatial hint (point)
result = model.segment(image, "cat", spatial_refs=[[0.5, 0.5]])

# With streaming
for update in model.segment(image, "cat", stream=True):
    if "bbox" in update and not update.get("completed"):
        print(f"Bbox: {update['bbox']}")  # Available in first message
    if "chunk" in update:
        print(update["chunk"], end="")  # Coarse path chunks
    if update.get("completed"):
        print(f"Final path: {update['path']}")  # Refined path
        print(f"Final bbox: {update['bbox']}")

encode_image(image)

Pre-encode an image for reuse across multiple calls.

Parameters:

• image — Image.Image or EncodedImage

Returns: Base64EncodedImage

encoded = model.encode_image(image)

Types

Links

• Website
• Playground
• GitHub