### Install Moondream Station from PyPI

Source: https://docs.moondream.ai/station

Installs the Moondream Station package using pip. This is the simplest way to get started.

```bash
pip install moondream-station
```

--------------------------------

### Install Moondream Station from Source

Source: https://docs.moondream.ai/station

Installs Moondream Station by cloning the repository and installing it in editable mode. This is useful for development or when needing the latest unreleased features.

```bash
git clone https://github.com/m87-labs/moondream-station.git
cd moondream-station
pip install -e .
```

--------------------------------

### Settings Object Example (JSONL)

Source: https://docs.moondream.ai/batch

An example of the 'settings' object that can be included with 'caption' and 'query' skills. It allows customization of generation parameters like temperature, top_p, and max_tokens.

```json
{
  "settings": {
    "temperature": 0.7,
    "top_p": 0.9,
    "max_tokens": 256
  }
}
```

--------------------------------

### List Finetunes Response (GET /finetunes)

Source: https://docs.moondream.ai/finetuning/http-api-reference

This is an example of the response when listing all finetunes for an organization. It includes a list of finetune objects, each with its ID, name, rank, and timestamps. Pagination details like `next_cursor` and `has_more` are also provided.

```json
{
  "finetunes": [
    {
      "finetune_id": "01HXYZ...",
      "name": "my-finetune",
      "rank": 32,
      "created_at_ms": 1736937000000,
      "updated_at_ms": 1736937000000
    }
  ],
  "next_cursor": "eyJjIjoiMjAyNS0wMS0xNVQxMDozMDowMFoifQ==",
  "has_more": true
}
```

--------------------------------

### Set Up Moondream API Key and Start Application

Source: https://docs.moondream.ai/sample-projects/automatic-detection-labeling

This snippet demonstrates how to set your Moondream API key as an environment variable and then start your application using npm. Ensure you replace 'your_key_here' with your actual API key.

```bash
export MOONDREAM_API_KEY="your_key_here"
npm start  
```

--------------------------------

### Point Skill Example (JSONL)

Source: https://docs.moondream.ai/batch

An example of a JSON Lines (JSONL) object for the 'point' skill. It requires a base64-encoded image and the object to locate.

```json
{"skill": "point", "image": "<base64>", "object": "door handle"}
```

--------------------------------

### Query Skill Example (JSONL)

Source: https://docs.moondream.ai/batch

An example of a JSON Lines (JSONL) object for the 'query' skill. It requires a base64-encoded image and a question. Optionally, it can include a 'reasoning' flag and use 'images' for multi-image queries.

```json
{"skill": "query", "image": "<base64>", "question": "What is this?", "reasoning": true}
```

--------------------------------

### Example cURL Request with Finetuned Model

Source: https://docs.moondream.ai/finetuning/http-api-reference

An example cURL command demonstrating how to make a POST request to the /query endpoint using a finetuned model. It includes the necessary headers and a JSON payload with the model identifier, image URL, and question.

```bash
curl -X POST https://api.moondream.ai/v1/query \
  -H "X-Moondream-Auth: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "model": "moondream3-preview/01HXYZ...@500", \
    "image_url": "data:image/jpeg;base64,...", \
    "question": "What do you see?" \
  }'
```

--------------------------------

### Install Moondream Python SDK

Source: https://docs.moondream.ai/quickstart

Install the Moondream Python SDK using pip. This command is essential for integrating Moondream's AI capabilities into Python applications.

```bash
pip install moondream
```

--------------------------------

### Detect Skill Example (JSONL)

Source: https://docs.moondream.ai/batch

An example of a JSON Lines (JSONL) object for the 'detect' skill. It requires a base64-encoded image and the object to detect.

```json
{"skill": "detect", "image": "<base64>", "object": "car"}
```

--------------------------------

### Install Moondream SDK (Node.js)

Source: https://docs.moondream.ai/quickstart

Installs the Moondream SDK for Node.js projects using npm. This command is the first step to integrating Moondream's capabilities into your JavaScript applications.

```bash
npm install moondream
```

--------------------------------

### API Key Setup

Source: https://docs.moondream.ai/sample-projects/automatic-detection-labeling

Instructions on how to set up your Moondream API key for authentication.

```APIDOC
## API Key Setup

To authenticate your requests, you need to set your Moondream API key as an environment variable.

### Environment Variable

```bash
export MOONDREAM_API_KEY="your_key_here"
```

### Usage

This key should be included in the `X-Moondream-Auth` header for your API requests.
```

--------------------------------

### Caption Skill Example (JSONL)

Source: https://docs.moondream.ai/batch

An example of a JSON Lines (JSONL) object for the 'caption' skill. It includes the skill type, a base64-encoded image, and an optional length parameter.

```json
{"skill": "caption", "image": "<base64>", "length": "short"}
```

--------------------------------

### Install Dependencies for Moondream

Source: https://docs.moondream.ai/transformers

Installs the necessary Python packages for using Moondream with Hugging Face Transformers. Requires transformers, torch, accelerate, and Pillow.

```bash
pip install "transformers>=4.51.1" "torch>=2.7.0" "accelerate>=1.10.0" "Pillow>=11.0.0"
```

--------------------------------

### Node.js SDK Query with Reasoning

Source: https://docs.moondream.ai/reasoning

This Node.js example demonstrates initializing the Moondream AI client and performing an image query with reasoning enabled. It uses the 'fs' module to read the image file and logs the answer from the result.

```javascript
import { vl } from 'moondream';
import fs from 'fs';

// Initialize with your API key
const model = new vl({ apiKey: 'YOUR_API_KEY' });

// Load an image
const image = fs.readFileSync('path/to/image.jpg');

// Query with reasoning enabled
const result = await model.query({
  image: image,
  question: 'What is in this image?',
  reasoning: true
});
console.log(result.answer);
```

--------------------------------

### Skill Request: Query (POST /rollouts)

Source: https://docs.moondream.ai/finetuning/http-api-reference

Example of a 'query' skill request for generating rollouts. It includes the skill type, a question, an optional image URL, a flag for extended reasoning, and generation settings.

```json
{
  "skill": "query",
  "question": "What color is the car?",
  "image_url": "data:image/jpeg;base64,...",  // optional
  "reasoning": false,  // optional
  "settings": {
    "temperature": 1.0,
    "top_p": 1.0,
    "max_tokens": 128
  }
}
```

--------------------------------

### Using Finetuned Models with cURL

Source: https://docs.moondream.ai/batch

Example using cURL to complete a batch upload, specifying a finetuned model. This demonstrates how to set the `model` parameter in the request body.

```bash
curl -s -X POST "https://api.moondream.ai/v1/batch/$FILE_ID?action=mpu-complete&uploadId=$UPLOAD_ID" \
  -H "X-Moondream-Auth: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ 
    "parts": [...], 
    "model": "moondream3-preview/YOUR_FINETUNE_ID@STEP" 
  }'
```

--------------------------------

### GET /finetunes

Source: https://docs.moondream.ai/finetuning/http-api-reference

List all finetunes for your organization, with options for pagination.

```APIDOC
## GET /finetunes

### Description
List all finetunes for your organization.

### Method
GET

### Endpoint
`/v1/tuning/finetunes`

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum results per page (1–100) (default: 50)
- **cursor** (string) - Optional - Pagination cursor from previous response

### Response
#### Success Response (200)
- **finetunes** (array) - List of finetune objects.
  - **finetune_id** (string) - Unique identifier (ULID) for the finetune.
  - **name** (string) - Name of the finetune.
  - **rank** (integer) - LoRA rank of the finetune.
  - **created_at_ms** (integer) - Creation timestamp in milliseconds.
  - **updated_at_ms** (integer) - Last update timestamp in milliseconds.
- **next_cursor** (string) - Pagination cursor for the next page of results.
- **has_more** (boolean) - Indicates if there are more results available.

#### Response Example
```json
{
  "finetunes": [
    {
      "finetune_id": "01HXYZ...",
      "name": "my-finetune",
      "rank": 32,
      "created_at_ms": 1736937000000,
      "updated_at_ms": 1736937000000
    }
  ],
  "next_cursor": "eyJjIjoiMjAyNS0wMS0xNVQxMDozMDowMFoifQ==",
  "has_more": true
}
```

**Note:** Results are ordered by creation time (oldest first).
```

--------------------------------

### Launch Moondream Station

Source: https://docs.moondream.ai/station

Executes the command to start the Moondream Station application in your terminal.

```bash
moondream-station
```

--------------------------------

### Streaming Image Captioning with Moondream

Source: https://docs.moondream.ai/transformers

This example shows how to generate image captions with Moondream in a streaming fashion. It loads the model, opens an image, and then iterates through the caption tokens as they are generated, printing them immediately. This requires the transformers, PIL, and torch libraries.

```python
from transformers import AutoModelForCausalLM
from PIL import Image
import torch

model = AutoModelForCausalLM.from_pretrained(
    "vikhyatk/moondream2",
    revision="2025-01-09",
    trust_remote_code=True,
    device_map="mps",  # "cuda" for NVIDIA GPUs
)

image = Image.open("path/to/your/image.jpg")

for t in model.caption(image, length="normal", stream=True)[ "caption"]:
    print(t, end="", flush=True)
```

--------------------------------

### Skill Request: Detect (POST /rollouts)

Source: https://docs.moondream.ai/finetuning/http-api-reference

An example of a 'detect' skill request for generating rollouts. It includes the skill type, the objects to detect, an image URL, and generation settings, which can include `max_objects`.

```json
{
  "skill": "detect",
  "object": "vehicles",
  "image_url": "data:image/jpeg;base64,...",
  "settings": {
    "temperature": 1.0,
    "top_p": 1.0,
    "max_tokens": 256,
    "max_objects": 8
  }
}
```

--------------------------------

### Batch API - Upload and Submit

Source: https://docs.moondream.ai/batch

This section details the process of uploading a JSONL file for batch processing and submitting it for execution. It involves initializing a multipart upload, uploading file chunks, and completing the upload to start the batch job.

```APIDOC
## Batch API - Upload and Submit

### Description
This endpoint facilitates the asynchronous processing of large numbers of image-related requests by allowing users to upload a JSONL file. The process involves initializing a multipart upload, uploading the file in chunks, and then completing the upload to initiate the batch job.

### Method
POST, PUT

### Endpoint
- `POST /v1/batch?action=mpu-create` (Initialize Upload)
- `PUT /v1/batch/{fileId}?action=mpu-uploadpart&uploadId={uploadId}&partNumber={partNumber}` (Upload Part)
- `POST /v1/batch/{fileId}?action=mpu-complete&uploadId={uploadId}` (Complete Upload)

### Parameters
#### Path Parameters
- **fileId** (string) - Required - The unique identifier for the file being uploaded.
- **uploadId** (string) - Required - The identifier for the multipart upload session.
- **partNumber** (integer) - Required - The sequential number of the part being uploaded.

#### Query Parameters
- **action** (string) - Required - Specifies the action to perform: `mpu-create`, `mpu-uploadpart`, `mpu-complete`.
- **uploadId** (string) - Required for `mpu-uploadpart` and `mpu-complete` - The ID of the multipart upload.
- **partNumber** (integer) - Required for `mpu-uploadpart` - The number of the part being uploaded.

#### Request Body
##### `mpu-create` (POST /v1/batch?action=mpu-create)
No request body required.

##### `mpu-uploadpart` (PUT /v1/batch/{fileId}?action=mpu-uploadpart&uploadId={uploadId}&partNumber={partNumber})
- **file content** (binary) - Required - The content of the file chunk to upload.

##### `mpu-complete` (POST /v1/batch/{fileId}?action=mpu-complete&uploadId={uploadId})
- **parts** (array) - Required - A list of objects, each containing `partNumber` and `etag` for the uploaded parts.
  - **partNumber** (integer) - Required - The number of the uploaded part.
  - **etag** (string) - Required - The entity tag (hash) of the uploaded part.

### Request Example
```json
// cURL Example for completing upload:
{
  "parts": [
    {"partNumber": 1, "etag": "etag1"},
    {"partNumber": 2, "etag": "etag2"}
  ]
}
```

### Response
#### Success Response (200)
- **fileId** (string) - The identifier for the uploaded file.
- **uploadId** (string) - The identifier for the multipart upload session.
- **id** (string) - The identifier for the batch job submitted for processing.
- **etag** (string) - The entity tag (hash) of the uploaded part (for `mpu-uploadpart`).

#### Response Example
```json
// Example for mpu-create:
{
  "fileId": "unique-file-id",
  "uploadId": "unique-upload-id"
}

// Example for mpu-uploadpart:
{
  "etag": "generated-etag"
}

// Example for mpu-complete:
{
  "id": "batch-job-id",
  "message": "Batch job submitted successfully."
}
```
```

--------------------------------

### GET /finetunes/:finetuneId/checkpoints

Source: https://docs.moondream.ai/finetuning/http-api-reference

Lists saved checkpoints for a specific finetune, with support for pagination.

```APIDOC
## GET /finetunes/:finetuneId/checkpoints

### Description
List saved checkpoints for a finetune.

### Method
GET

### Endpoint
/finetunes/:finetuneId/checkpoints

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum results per page (1–100) (default: 50)
- **cursor** (string) - Optional - Pagination cursor from previous response

### Response
#### Success Response (200)
- **checkpoints** (array) - List of checkpoint objects
  - **checkpoint_id** (string) - Unique checkpoint identifier
  - **finetune_id** (string) - Finetune identifier
  - **step** (integer) - Training step number
  - **created_at_ms** (integer) - Unix timestamp in milliseconds
  - **updated_at_ms** (integer) - Unix timestamp in milliseconds
- **next_cursor** (string) - Cursor for the next page of results
- **has_more** (boolean) - Indicates if there are more results available

#### Response Example
```json
{
  "checkpoints": [
    {
      "checkpoint_id": "01JXYZ...",
      "finetune_id": "01HXYZ...",
      "step": 100,
      "created_at_ms": 1736937000000,
      "updated_at_ms": 1736937600000
    }
  ],
  "next_cursor": "eyJzIjo1MDB9",
  "has_more": true
}
```
```

--------------------------------

### Object Detection with cURL

Source: https://docs.moondream.ai/api

Example of how to perform Object Detection using the Moondream AI API with cURL. This requires specifying the image URL and the object to detect.

```curl
curl -X POST https://api.moondream.ai/v1/detect \
  -H 'Content-Type: application/json' \
  -H 'X-Moondream-Auth: YOUR_API_KEY' \
  -d '{
    "image_url": "data:image/jpeg;base64,/9j//gAQTGF2YzYxLjE5LjEwMQD/2wBDAAg+Pkk+SVVVVVVVVWRdZGhoaGRkZGRoaGhwcHCDg4NwcHBoaHBwfHyDg4+Tj4eHg4eTk5ubm7q6srLZ2eD/////xABZAAADAQEBAQAAAAAAAAAAAAAABgcFCAECAQEAAAAAAAAAAAAAAAAAAAAAEAADAAMBAQEBAAAAAAAAAAAAAQIDIREEURKBEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAGQAZAwESAAISAAMSAP/aAAwDAQACEQMRAD8A5/PQAAABirHyVS2mUip/Pm4/vQAih9ABuRUrVLqMEALVNead7/pFgAfc+d5NLSEEAAAA/9k=",
    "object": "moon"
  }'
```

--------------------------------

### Upload and Submit Batch Job using cURL

Source: https://docs.moondream.ai/batch

This cURL script demonstrates the multi-step process of uploading a batch job. It initializes a multipart upload, splits the input file into chunks, uploads each chunk, and finally completes the upload to start processing. It requires jq for JSON parsing.

```bash
# Step 1: Initialize multipart upload  
INIT=$(curl -s -X POST "https://api.moondream.ai/v1/batch?action=mpu-create" \  
  -H "X-Moondream-Auth: YOUR_API_KEY")  
  
FILE_ID=$(echo $INIT | jq -r '.fileId')  
UPLOAD_ID=$(echo $INIT | jq -r '.uploadId')  
  
# Step 2: Split file into 50MB chunks and upload each part  
CHUNK_SIZE=$((50 * 1024 * 1024))  
split -b $CHUNK_SIZE batch_input.jsonl chunk_  
  
PARTS="[]"  
PART_NUM=1  
for CHUNK in chunk_*; do  
  PART=$(curl -s -X PUT "https://api.moondream.ai/v1/batch/$FILE_ID?action=mpu-uploadpart&uploadId=$UPLOAD_ID&partNumber=$PART_NUM" \  
    -H "X-Moondream-Auth: YOUR_API_KEY" \  
    -H "Content-Type: application/octet-stream" \  
    --data-binary @$CHUNK)  
  ETAG=$(echo $PART | jq -r '.etag')  
  PARTS=$(echo $PARTS | jq ". + [{"partNumber": $PART_NUM, "etag": \"$ETAG\"}]")  
  rm $CHUNK  
  PART_NUM=$((PART_NUM + 1))  
done  
  
# Step 3: Complete upload and start processing  
BATCH=$(curl -s -X POST "https://api.moondream.ai/v1/batch/$FILE_ID?action=mpu-complete&uploadId=$UPLOAD_ID" \  
  -H "X-Moondream-Auth: YOUR_API_KEY" \  
  -H "Content-Type: application/json" \  
  -d "{\"parts\": $PARTS}")  
  
BATCH_ID=$(echo $BATCH | jq -r '.id')  
echo "Batch submitted: $BATCH_ID"  

```

--------------------------------

### Complete Upload and Start Processing (Python)

Source: https://docs.moondream.ai/batch

Completes a multipart upload and initiates batch processing. It requires the BASE_URL, file_id, upload_id, headers, and a list of uploaded parts. The response contains the batch ID.

```Python
batch = requests.post(
    f"{BASE_URL}/{file_id}?action=mpu-complete&uploadId={upload_id}",
    headers=headers,
    json={"parts": parts}
).json()

print(f"Batch submitted: {batch['id']}")
```

--------------------------------

### Visual Question Answering with cURL

Source: https://docs.moondream.ai/api

Example of how to perform Visual Question Answering using the Moondream AI API with cURL. This involves sending a POST request with an image URL and a question.

```curl
curl -X POST https://api.moondream.ai/v1/query \
  -H 'Content-Type: application/json' \
  -H 'X-Moondream-Auth: YOUR_API_KEY' \
  -d '{
    "image_url": "data:image/jpeg;base64,/9j//gAQTGF2YzYxLjE5LjEwMQD/2wBDAAg+Pkk+SVVVVVVVVWRdZGhoaGRkZGRoaGhwcHCDg4NwcHBoaHBwfHyDg4+Tj4eHg4eTk5ubm7q6srLZ2eD/////xABZAAADAQEBAQAAAAAAAAAAAAAABgcFCAECAQEAAAAAAAAAAAAAAAAAAAAAEAADAAMBAQEBAAAAAAAAAAAAAQIDIREEURKBEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAGQAZAwESAAISAAMSAP/aAAwDAQACEQMRAD8A5/PQAAABirHyVS2mUip/Pm4/vQAih9ABuRUrVLqMEALVNead7/pFgAfc+d5NLSEEAAAA/9k=",
    "question": "What is in this image?"
  }'
```

--------------------------------

### Multipart Upload and Batch Processing (Node.js)

Source: https://docs.moondream.ai/batch

Handles the entire multipart upload process, from initialization to completing the upload and starting batch processing. It reads input from a local file, uploads it in chunks, and then sends a completion request. Requires API key, base URL, and a local file named 'batch_input.jsonl'.

```javascript
import fs from 'fs';

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.moondream.ai/v1/batch';
const headers = { 'X-Moondream-Auth': API_KEY };
const CHUNK_SIZE = 50 * 1024 * 1024; // 50MB chunks

// Step 1: Initialize multipart upload
const init = await fetch(`${BASE_URL}?action=mpu-create`, {
  method: 'POST', headers
}).then(r => r.json());

const { fileId, uploadId } = init;

// Step 2: Upload in chunks
const fileData = fs.readFileSync('batch_input.jsonl');
const parts = [];

for (let i = 0; i < fileData.length; i += CHUNK_SIZE) {
  const chunk = fileData.subarray(i, i + CHUNK_SIZE);
  const partNumber = Math.floor(i / CHUNK_SIZE) + 1;

  const part = await fetch(
    `${BASE_URL}/${fileId}?action=mpu-uploadpart&uploadId=${uploadId}&partNumber=${partNumber}`,
    {
      method: 'PUT',
      headers: { ...headers, 'Content-Type': 'application/octet-stream' },
      body: chunk
    }
  ).then(r => r.json());

  parts.push({ partNumber, etag: part.etag });
}

// Step 3: Complete upload and start processing
const batch = await fetch(
  `${BASE_URL}/${fileId}?action=mpu-complete&uploadId=${uploadId}`,
  {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ parts })
  }
).then(r => r.json());

console.log(`Batch submitted: ${batch.id}`);
```

--------------------------------

### Object Pointing with cURL

Source: https://docs.moondream.ai/api

Example of how to get precise center coordinates for objects using the Moondream AI API with cURL. This endpoint requires the image URL and the object of interest.

```curl
curl -X POST https://api.moondream.ai/v1/point \
  -H 'Content-Type: application/json' \
  -H 'X-Moondream-Auth: YOUR_API_KEY' \
  -d '{
    "image_url": "data:image/jpeg;base64,/9j//gAQTGF2YzYxLjE5LjEwMQD/2wBDAAg+Pkk+SVVVVVVVVWRdZGhoaGRkZGRoaGhwcHCDg4NwcHBoaHBwfHyDg4+Tj4eHg4eTk5ubm7q6srLZ2eD/////xABZAAADAQEBAQAAAAAAAAAAAAAABgcFCAECAQEAAAAAAAAAAAAAAAAAAAAAEAADAAMBAQEBAAAAAAAAAAAAAQIDIREEURKBEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAGQAZAwESAAISAAMSAP/aAAwDAQACEQMRAD8A5/PQAAABirHyVS2mUip/Pm4/vQAih9ABuRUrVLqMEALVNead7/pFgAfc+d5NLSEEAAAA/9k=",
    "object": "moon"
  }'
```

--------------------------------

### API: Get Batch Status (GET)

Source: https://docs.moondream.ai/batch

Fetches the current status of a specific batch job using its `batchId`. The status indicates the progress of the batch processing.

```http
GET /v1/batch/:batchId
```

--------------------------------

### Query Image with Python

Source: https://docs.moondream.ai/skills/query

This Python snippet demonstrates how to use the Moondream AI library to ask questions about an image. It includes initializing the model with an API key, loading an image, performing a query, and optionally streaming the response. Dependencies include the 'moondream' library and 'Pillow' for image handling.

```python
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)
```

--------------------------------

### Get Finetune Details Response (GET /finetunes/:finetuneId)

Source: https://docs.moondream.ai/finetuning/http-api-reference

This JSON object represents the details of a specific finetune, retrieved using its unique `finetune_id`. It includes the finetune's ID, name, rank, and creation/update timestamps.

```json
{
  "finetune_id": "01HXYZ...",
  "name": "my-finetune",
  "rank": 32,
  "created_at_ms": 1736937000000,
  "updated_at_ms": 1736937000000
}
```

--------------------------------

### POST /finetunes

Source: https://docs.moondream.ai/finetuning/http-api-reference

Create a new finetune. If a finetune with the same name and rank already exists, the existing ID is returned. Otherwise, a new finetune is created.

```APIDOC
## POST /finetunes

### Description
Create a new finetune.

### Method
POST

### Endpoint
`/v1/tuning/finetunes`

### Parameters
#### Request Body
- **name** (string) - Required - Unique name for this finetune (alphanumeric, hyphens, underscores)
- **rank** (integer) - Required - LoRA rank: 8, 16, 24, or 32 (must be multiple of 8; higher = more capacity, but slower)

### Request Example
```json
{
  "name": "my-finetune",
  "rank": 32
}
```

### Response
#### Success Response (200)
- **finetune_id** (string) - Unique identifier (ULID) for the finetune. Use this ID for all subsequent operations.

#### Response Example
```json
{
  "finetune_id": "01HXYZ..."
}
```

**Note:** If a finetune with the same name already exists with the same rank, the existing `finetune_id` is returned (idempotent). If the name exists with a different rank, returns 409 Conflict.
```

--------------------------------

### Prepare Batch Input File

Source: https://docs.moondream.ai/batch

Creates a JSONL file where each line represents a single API request. Each request includes an optional 'id', the 'skill' to perform (e.g., 'caption', 'query', 'detect'), the 'image' data (base64 encoded), and skill-specific parameters.

```jsonl
{"id": "img_001", "skill": "caption", "image": "<base64>", "length": "normal"}  
{"id": "img_002", "skill": "query", "image": "<base64>", "question": "What color is the car?"}  
{"id": "img_003", "skill": "detect", "image": "<base64>", "object": "person"}  

```

--------------------------------

### Get Batch Status

Source: https://docs.moondream.ai/batch

Retrieves the status and results of a specific batch job.

```APIDOC
## GET /v1/batch/:batchId

### Description
Retrieves the status and results of a specific batch job.

### Method
GET

### Endpoint
/v1/batch/:batchId

### Parameters
#### Path Parameters
- **batchId** (string) - Required - The ID of the batch to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The ID of the batch.
- **status** (string) - The current status of the batch. Possible values:
  - `chunking`: File is being validated and split.
  - `processing`: Requests are being processed.
  - `completed`: All requests finished.
  - `failed`: Batch failed (see `error` field).
- **results** (array) - An array of result objects for each line in the batch (if status is 'completed').
- **error** (object) - An error object if the batch status is 'failed'.

#### Response Example (Successful)
```json
{
  "line_index": 0,
  "id": "img_001",
  "status": "ok",
  "result": { "caption": "A golden retriever playing in a park..." },
  "usage": { "input_tokens": 150, "output_tokens": 25 }
}
```

#### Response Example (Failed)
```json
{
  "line_index": 1,
  "id": "img_002",
  "status": "error",
  "error": { "code": "image_decode_failed", "message": "Invalid image data" }
}
```
```

--------------------------------

### Manage Moondream Models

Source: https://docs.moondream.ai/station

Provides CLI commands to list available Moondream models and switch between them.

```bash
models
models switch <model>
```

--------------------------------

### Python SDK Query with Reasoning

Source: https://docs.moondream.ai/reasoning

This Python code snippet shows how to initialize the Moondream AI client and query an image with reasoning enabled. It uses the Pillow library to load the image and expects the result's answer to be printed.

```python
import moondream as md
from PIL import Image

# Initialize with your API key
model = md.vl(api_key="YOUR_API_KEY")

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

# Query with reasoning enabled
result = model.query(image, "What is in this image?", reasoning=True)
print(result["answer"])
```

--------------------------------

### GET /finetunes/:finetuneId

Source: https://docs.moondream.ai/finetuning/http-api-reference

Retrieve details for a specific finetune using its ID.

```APIDOC
## GET /finetunes/:finetuneId

### Description
Get details for a specific finetune.

### Method
GET

### Endpoint
`/v1/tuning/finetunes/:finetuneId`

### Parameters
#### Path Parameters
- **finetuneId** (string) - Required - The ID of the finetune to retrieve.

### Response
#### Success Response (200)
- **finetune_id** (string) - Unique identifier (ULID) for the finetune.
- **name** (string) - Name of the finetune.
- **rank** (integer) - LoRA rank of the finetune.
- **created_at_ms** (integer) - Creation timestamp in milliseconds.
- **updated_at_ms** (integer) - Last update timestamp in milliseconds.

#### Response Example
```json
{
  "finetune_id": "01HXYZ...",
  "name": "my-finetune",
  "rank": 32,
  "created_at_ms": 1736937000000,
  "updated_at_ms": 1736937000000
}
```

**Note:** Returns 404 if the finetune does not exist.
```

--------------------------------

### Using Finetuned Models

Source: https://docs.moondream.ai/batch

Demonstrates how to specify a finetuned model when completing an upload.

```APIDOC
## POST /v1/batch/:fileId?action=mpu-complete&uploadId={uploadId} (with finetuned model)

### Description
Completes the multi-part upload process, specifying a finetuned model for processing.

### Method
POST

### Endpoint
/v1/batch/:fileId?action=mpu-complete&uploadId={uploadId}

### Parameters
#### Path Parameters
- **fileId** (string) - Required - The file ID obtained from the initialize upload step.

#### Query Parameters
- **action** (string) - Required - Must be 'mpu-complete'.
- **uploadId** (string) - Required - The upload ID obtained from the initialize upload step.

#### Request Body
- **parts** (array) - Required - Array of uploaded parts, each containing `partNumber` and `etag`.
  - **partNumber** (integer) - Required - The number of the part.
  - **etag** (string) - Required - The entity tag of the uploaded part.
- **model** (string) - Required - The finetuned model to use. Format: `moondream3-preview/finetune_id@step`.
  - `finetune_id`: Your finetune's ID (e.g., `01JQXYZ...`).
  - `step`: The checkpoint step number.

### Request Example
```bash
curl -s -X POST "https://api.moondream.ai/v1/batch/$FILE_ID?action=mpu-complete&uploadId=$UPLOAD_ID" \
  -H "X-Moondream-Auth: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [...],
    "model": "moondream3-preview/YOUR_FINETUNE_ID@STEP"
  }'
```

### Notes
- All lines in a batch use the same model.
- The finetune must have a saved checkpoint.
```

--------------------------------

### POST /point - Object Pointing

Source: https://docs.moondream.ai/api

Get the precise center coordinates for specified objects within an image.

```APIDOC
## POST /point

### Description
Get precise center coordinates for objects.

### Method
POST

### Endpoint
https://api.moondream.ai/v1/point

### Parameters
#### Request Body
- **image_url** (string) - Required - The URL or base64 encoded data of the image.
- **object** (string) - Required - The name of the object to find the center of.

### Request Example
```json
{
  "image_url": "data:image/jpeg;base64,/9j//gAQTGF2YzYxLjE5LjEwMQD/2wBDAAg+Pkk+SVVVVVVVVWRdZGhoaGRkZGRoaGhwcHCDg4NwcHBoaHBwfHyDg4+Tj4eHg4eTk5ubm7q6srLZ2eD/////xABZAAADAQEBAQAAAAAAAAAAAAAABgcFCAECAQEAAAAAAAAAAAAAAAAAAAAAEAADAAMBAQEBAAAAAAAAAAAAAQIDIREEURKBEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAGQAZAwESAAISAAMSAP/aAAwDAQACEQMRAD8A5/PQAAABirHyVS2mUip/Pm4/vQAih9ABuRUrVLqMEALVNead7/pFgAfc+d5NLSEEAAAA/9k=",
  "object": "moon"
}
```

### Response
#### Success Response (200)
- **request_id** (string) - A unique identifier for the request.
- **points** (array) - An array of points, each representing the center of a detected object.
  - **x** (number) - The x-coordinate of the object's center.
  - **y** (number) - The y-coordinate of the object's center.

#### Response Example
```json
{
  "request_id": "2025-03-25_point_2025-03-25-21:00:39-715d03",
  "points": [
    {
      "x": 0.65,
      "y": 0.42
    }
  ]
}
```
```

--------------------------------

### Query Image with Moondream Python SDK

Source: https://docs.moondream.ai/quickstart

Perform Visual Question Answering using the Moondream Python SDK. This code snippet demonstrates initializing the model with an API key, loading an image, and querying it with a natural language question. The result, containing the answer, is then printed.

```python
import moondream as md
from PIL import Image

# Initialize with your 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 is in this image?")
print(result["answer"])
```

--------------------------------

### API: List Batches (GET)

Source: https://docs.moondream.ai/batch

Retrieves a list of previously submitted batch jobs. Supports pagination using `limit` and `cursor` parameters.

```http
GET /v1/batch?limit={n}&cursor={cursor}
```

--------------------------------

### POST /v1/detect - Get Bounding Boxes

Source: https://docs.moondream.ai/sample-projects/automatic-detection-labeling

This endpoint detects the bounding box coordinates for a specified object within an image.

```APIDOC
## POST /v1/detect

### Description

Given an image and an object name, this endpoint returns the bounding box coordinates for all instances of that object found in the image.

### Method

`POST`

### Endpoint

`https://api.moondream.ai/v1/detect`

### Parameters

#### Request Body

- **image_url** (string) - Required - The image to process, typically base64 encoded.
- **object** (string) - Required - The name of the object to detect.
- **reasoning** (boolean) - Optional - Enable grounded reasoning for better accuracy. Defaults to `false`.

### Request Example

```json
{
  "image_url": "<base64_encoded_image_data>",
  "object": "dog",
  "reasoning": true
}
```

### Response

#### Success Response (200)

- **objects** (array) - An array of detected object instances.
  - **x_min** (number) - The minimum x-coordinate of the bounding box (normalized 0-1).
  - **y_min** (number) - The minimum y-coordinate of the bounding box (normalized 0-1).
  - **x_max** (number) - The maximum x-coordinate of the bounding box (normalized 0-1).
  - **y_max** (number) - The maximum y-coordinate of the bounding box (normalized 0-1).
- **reasoning** (object) - If `reasoning` was true, contains detailed reasoning information.

#### Response Example

```json
{
  "objects": [
    {
      "x_min": 0.1,
      "y_min": 0.2,
      "x_max": 0.5,
      "y_max": 0.6
    },
    {
      "x_min": 0.6,
      "y_min": 0.3,
      "x_max": 0.9,
      "y_max": 0.7
    }
  ],
  "reasoning": {
    "hallucination": 0.02,
    "relevant": 0.98
  }
}
```
```

--------------------------------

### Generate Rollouts for Evaluation (Deterministic)

Source: https://docs.moondream.ai/finetuning/using-the-interface

This endpoint is used for evaluating model performance. It generates a single rollout with the temperature setting set to zero for deterministic output. This ensures consistent predictions for accurate measurement.

```json
// POST /rollouts
{
  "finetune_id": "01HXYZ...",
  "num_rollouts": 1,
  "request": {
    "skill": "detect",
    "object": "vehicles",
    "image_url": "data:image/jpeg;base64,/9j/4AAQ...",
    "settings": {
      "temperature": 0
    }
  }
}

```

--------------------------------

### Control Moondream Station Service

Source: https://docs.moondream.ai/station

Commands to manage the Moondream Station inference service, including starting, stopping, and restarting the server on a specified port.

```bash
start [port]
stop
restart
```

--------------------------------

### API: Initialize Batch Upload (POST)

Source: https://docs.moondream.ai/batch

Initiates a multi-part upload (MPU) for a batch job. Requires the `mpu-create` action. Returns essential IDs for subsequent upload steps.

```http
POST /v1/batch?action=mpu-create
```

--------------------------------

### Image Segmentation with cURL

Source: https://docs.moondream.ai/api

Example of generating SVG path masks for objects within an image using the Moondream AI API with cURL. This endpoint requires the image URL and the object to segment.

```curl
curl -X POST https://api.moondream.ai/v1/segment \
  -H 'Content-Type: application/json' \
  -H 'X-Moondream-Auth: YOUR_API_KEY' \
  -d '{
    "image_url": "data:image/jpeg;base64,...",
    "object": "cat"
  }'
```

--------------------------------

### GET /finetunes/:finetuneId/checkpoints Response

Source: https://docs.moondream.ai/finetuning/http-api-reference

The response from the /finetunes/:finetuneId/checkpoints endpoint, listing saved checkpoints for a finetune. It includes checkpoint details, a pagination cursor, and a flag indicating if more results are available.

```json
{
  "checkpoints": [
    {
      "checkpoint_id": "01JXYZ...",
      "finetune_id": "01HXYZ...",
      "step": 100,
      "created_at_ms": 1736937000000,
      "updated_at_ms": 1736937600000
    }
  ],
  "next_cursor": "eyJzIjo1MDB9",
  "has_more": true
}
```

--------------------------------

### Query Image with Node.js

Source: https://docs.moondream.ai/skills/query

This Node.js snippet shows how to query an image using the Moondream AI library. It covers initializing the model with an API key, loading an image file, sending a query, and handling streamed responses. It requires the 'moondream' package and Node.js file system module.

```javascript
import { vl } from 'moondream';
import fs from 'fs';

// Initialize with API key
const model = new vl({ apiKey: "your-api-key" });

// Load an image
const image = fs.readFileSync("path/to/image.jpg");

// Ask a question
const result = await model.query({
  image: image,
  question: "What's in this image?"
});
console.log(`Answer: ${result.answer}`);
console.log(`Request ID: ${result.request_id}`);

// Stream the response
const stream = await model.query({
  image: image,
  question: "What's in this image?",
  stream: true
});
for await (const chunk of stream.answer) {
  process.stdout.write(chunk);
}
```