OpenAI Compatibility

If you’re already using OpenAI’s Vision API in your applications, you can easily switch to Moondream. Our API is designed to be compatible with OpenAI’s client libraries, which means you can keep using the same code structure, just change a few configuration settings.

What is Moondream?

Moondream-2B is a lightweight vision-language model optimized for visual understanding tasks. It excels at answering questions about images, describing scenes, identifying objects and attributes, and basic text recognition. While more compact than larger models, it provides efficient and accurate responses for straightforward visual question-answering.

As a 2B parameter model, it has some limitations to keep in mind: descriptions may be less detailed than larger models, complex multi-step reasoning can be challenging, and it may struggle with edge cases like very low quality images or advanced spatial understanding. For best results, focus on direct questions about image content rather than complex reasoning chains.

The transition to Moondream takes less than 5 minutes.

Changes Needed

✓

Update Base URL

Change https://api.openai.com/v1 to https://api.moondream.ai/v1

✓

Replace API Key

Use your Moondream API key instead of OpenAI’s. Get your key from https://console.moondream.ai/

✓

Update Model Name

Use moondream-2B instead of gpt-4-vision-preview

from openai import OpenAI
import base64
 
client = OpenAI(
-     base_url="https://api.openai.com/v1",
+     base_url="https://api.moondream.ai/v1",
-    api_key="your-openai-key"
+    api_key="your-moondream-key"
)
 
response = client.chat.completions.create(
-    model="gpt-4o",
+    model="moondream-2B",
    messages=[...]
)

💡

If you get stuck, our Discord community is here to help.

⚠️

Keep your API key secure and never expose it in client-side code. By default, your account gets 60 requests per minute and 5,000 requests per day. Contact us to increase your limits.

Working with Local Images

When you want to analyze an image from your computer, you need to convert it into a format that can be sent over the internet. This is where Base64 encoding comes in - it’s a way to represent binary data as a string of text.

import base64
 
# Convert image to base64 string
with open("image.jpg", "rb") as f:
    base64_image = base64.b64encode(f.read()).decode('utf-8')
 
# Use in API request
response = client.chat.completions.create(
    model="moondream-2B",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}
            },
            {"type": "text", "text": "Describe this image"}
        ]
    }]
)

Using Streaming Responses

Streaming lets you receive the model’s response word by word, creating a more interactive experience.

# Enable streaming
response = client.chat.completions.create(
    model="moondream-2B",
    messages=[...],
    stream=True  # Get word-by-word responses
)
 
# Process the stream
for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Usage statistics are only available for non-streaming responses.

Error Handling

Since we follow OpenAI’s error format, you can use the same error handling code you already have. For detailed information about error types and handling strategies, refer to OpenAI’s error documentation. If you’re already handling OpenAI API errors, no changes are needed for Moondream.

Specifications