Skip to main content
ModelRunner
moondream avatar

Moondream 3 Preview (Query) API

moondream/moondream3-preview/query

Ask a natural-language question about an image and get a text answer, with frontier-level visual reasoning, OCR, and object understanding.

caption
Priced per token
OpenAPI

Model Input

Input

URL of the image to ask about.

Question to ask about the image.

Include the model's detailed reasoning in the response.

Min: 0 - Max: 1

Sampling temperature. 0 is deterministic; higher values (up to 1) increase variety.

Min: 0 - Max: 1

Nucleus sampling probability mass.

You need to be logged in to run this model and view results.
Log in

Model Output

Output

A man wearing a red hard hat and safety glasses operates a blue industrial machine.

Generated in 2.816 seconds
Logs (1 lines)

Model Example Requests

Examples

Moondream 3 Preview (Query) API

Moondream 3 Preview (Query) is a image-to-text AI model by moondream. On ModelRunner it runs through a REST API or via MCP from any AI assistant with pay-per-use pricing.

POST https://queue.modelrunner.run/moondream/moondream3-preview/query

cURL

# Submit a request to the queue. Input fields go at the top level of the
# body. The optional reserved "metadata" object holds your own flat string
# tags — stored on the request, never sent to the model; filter later with
# GET https://queue.modelrunner.run/requests?metadata=<url-encoded JSON>.
curl -X POST https://queue.modelrunner.run/moondream/moondream3-preview/query \
  -H "Authorization: Key $MRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is in this image? Answer in one short sentence.",
    "image_url": "https://media.modelrunner.ai/unuFWBxAAKhBbmC8-moondream3_query_demo.jpg",
    "reasoning": false,
    "temperature": 0,
    "metadata": {
      "project": "my-project"
    }
  }'
# → { "request_id": "...", "status_url": "...", "response_url": "..." }

# Poll status_url until "COMPLETED", then fetch the result
curl "https://queue.modelrunner.run/moondream/moondream3-preview/query/requests/$REQUEST_ID/status" \
  -H "Authorization: Key $MRUN_API_KEY"
curl "https://queue.modelrunner.run/moondream/moondream3-preview/query/requests/$REQUEST_ID" \
  -H "Authorization: Key $MRUN_API_KEY"

JavaScript

import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("moondream/moondream3-preview/query", {
  input: {
    "prompt": "What is in this image? Answer in one short sentence.",
    "image_url": "https://media.modelrunner.ai/unuFWBxAAKhBbmC8-moondream3_query_demo.jpg",
    "reasoning": false,
    "temperature": 0
  },
});
console.log(result);

Python

import os
import requests

headers = {"Authorization": f"Key {os.environ['MRUN_API_KEY']}"}

submitted = requests.post(
    "https://queue.modelrunner.run/moondream/moondream3-preview/query",
    headers=headers,
    json={
      "prompt": "What is in this image? Answer in one short sentence.",
      "image_url": "https://media.modelrunner.ai/unuFWBxAAKhBbmC8-moondream3_query_demo.jpg",
      "reasoning": false,
      "temperature": 0
    },
).json()

# Poll submitted["status_url"] until "COMPLETED", then:
result = requests.get(submitted["response_url"], headers=headers).json()

Input parameters

NameTypeRequiredDescription
image_urlstring (uri)yesURL of the image to ask about.
promptstringyesQuestion to ask about the image.
reasoningbooleannoInclude the model's detailed reasoning in the response. Default: true.
temperaturenumbernoSampling temperature. 0 is deterministic; higher values (up to 1) increase variety. Default: 0.
top_pnumbernoNucleus sampling probability mass.

Machine-readable: OpenAPI schema · llms.txt

Use Moondream 3 Preview (Query) from Claude & Cursor (MCP)

Point Claude Code, Claude Desktop, Cursor, or any MCP client at the ModelRunner MCP server and Moondream 3 Preview (Query) becomes a tool your assistant can call directly — it authorizes via OAuth (no API key in config) and runs this model with the run_model tool using the endpoint moondream/moondream3-preview/query.

MCP client config (Claude Desktop, Cursor)

{
  "mcpServers": {
    "modelrunner": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.modelrunner.run/mcp"]
    }
  }
}

Claude Code

claude mcp add --transport http modelrunner https://mcp.modelrunner.run/mcp

Then ask your assistant, for example: “Run moondream/moondream3-preview/query on ModelRunner to generate text”. MCP setup guide.

Model Details

Model Details

Moondream 3 Preview answers natural-language questions about an image. Pass an image URL and a question ("What is the person doing?", "How many cars are in the lot?", "What does the sign say?") and it returns a concise text answer. It is a compact, efficient vision-language model built for frontier-level visual reasoning — reading text in a scene (OCR), counting and identifying objects, describing what is happening, and grounding answers in fine image detail — while staying fast and inexpensive to run at scale.

## Best for - Visual question answering: asking free-form questions about a photo, screenshot, chart, or document image - Reading text inside images (signs, labels, receipts, handwriting) and answering questions about it - Counting, identifying, and locating objects or people in a scene - Describing image content for accessibility, moderation triage, or content tagging - High-volume image understanding where cost-per-call and latency matter

## Choose another model when - You want to generate or edit an image rather than describe one — use a text-to-image or image-editing model - You have no image and only need a text answer — use a text-only language model - You need pixel-precise bounding boxes or segmentation masks as structured output rather than a written answer — use a detection or segmentation model

## Tips - Ask one clear, specific question per call; specifying the desired answer format ("answer in one short sentence", "reply with just the number") tightens the output. - Leave `temperature` at its default of 0 for deterministic, factual answers; raise it (up to 1) only when you want more varied phrasing. - Keep `reasoning` enabled (default) to also receive the model's step-by-step reasoning trace alongside the answer; set it to `false` for just the final answer and lower latency.

## Advanced Configuration - `reasoning` (boolean, default `true`): when `true`, the response includes the model's detailed reasoning behind the answer; when `false`, the reasoning trace is omitted and only the answer is returned. - `temperature` (number 0–1, default `0`): sampling temperature for the answer. `0` is deterministic; higher values increase variety. - `top_p` (number 0–1): nucleus-sampling probability mass, an alternative way to control answer diversity.

To run via the ModelRunner JavaScript client: ```js import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("moondream/moondream3-preview/query", { input: { image_url: "https://storage.googleapis.com/falserverless/example_inputs/moondream-3-preview/query_in.jpg", prompt: "What is in this image? Answer in one short sentence.", reasoning: false, }, }); ```