From daee12be88378616d3bdb9d26c3a5c5e8f6e171e Mon Sep 17 00:00:00 2001
From: Vikhyat Korrapati <vikhyatk@gmail.com>
Date: Tue, 7 Jul 2026 18:30:56 -0700
Subject: [PATCH 1/3] Document Moondream 3.1 model usage

---
 docs/api.md                            | 15 ++++++++++++-
 docs/batch.md                          | 20 ++++++++++--------
 docs/finetuning/http-api-reference.mdx |  5 +++--
 docs/openai.md                         | 29 ++++++++++++++++----------
 docs/quickstart.md                     |  4 ++++
 docs/reasoning.md                      |  2 +-
 docs/skills/caption.md                 | 12 +++++++++++
 docs/skills/detect.md                  |  9 ++++++++
 docs/skills/point.md                   |  9 ++++++++
 docs/skills/query.md                   | 11 ++++++++++
 docs/skills/segment.md                 | 12 +++++++++++
 docs/streaming.md                      |  2 +-
 src/components/RateLimitsTable.tsx     | 21 ++++++++++++++++++-
 13 files changed, 125 insertions(+), 26 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 91b2dab..e41ba43 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -13,6 +13,15 @@ All API requests use this base URL with skill-specific endpoints (`/query`, `/de
 
 Prefer an OpenAI-style chat interface? Moondream also offers an [OpenAI-compatible `/v1/chat/completions` endpoint](/openai) with multi-turn conversations, streaming, and image inputs.
 
+### Model selection
+
+Every direct API request must include a `model` field. Supported model IDs:
+
+| Model | Notes |
+|-------|-------|
+| `moondream3.1-9B-A2B` | Moondream 3.1 model. Finetuned checkpoints are not supported. |
+| `moondream3-preview` | Moondream 3 Preview model. Use this for finetuned checkpoints with `moondream3-preview/{finetune_id}@{step}`. |
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
@@ -26,6 +35,7 @@ curl -X POST https://api.moondream.ai/v1/query \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "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?"
   }'
@@ -49,6 +59,7 @@ curl -X POST https://api.moondream.ai/v1/detect \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,/9j//gAQTGF2YzYxLjE5LjEwMQD/2wBDAAg+Pkk+SVVVVVVVVWRdZGhoaGRkZGRoaGhwcHCDg4NwcHBoaHBwfHyDg4+Tj4eHg4eTk5ubm7q6srLZ2eD/////xABZAAADAQEBAQAAAAAAAAAAAAAABgcFCAECAQEAAAAAAAAAAAAAAAAAAAAAEAADAAMBAQEBAAAAAAAAAAAAAQIDIREEURKBEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAGQAZAwESAAISAAMSAP/aAAwDAQACEQMRAD8A5/PQAAABirHyVS2mUip/Pm4/vQAih9ABuRUrVLqMEALVNead7/pFgAfc+d5NLSEEAAAA/9k=",
     "object": "moon"
   }'
@@ -79,6 +90,7 @@ curl -X POST https://api.moondream.ai/v1/point \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,/9j//gAQTGF2YzYxLjE5LjEwMQD/2wBDAAg+Pkk+SVVVVVVVVWRdZGhoaGRkZGRoaGhwcHCDg4NwcHBoaHBwfHyDg4+Tj4eHg4eTk5ubm7q6srLZ2eD/////xABZAAADAQEBAQAAAAAAAAAAAAAABgcFCAECAQEAAAAAAAAAAAAAAAAAAAAAEAADAAMBAQEBAAAAAAAAAAAAAQIDIREEURKBEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAGQAZAwESAAISAAMSAP/aAAwDAQACEQMRAD8A5/PQAAABirHyVS2mUip/Pm4/vQAih9ABuRUrVLqMEALVNead7/pFgAfc+d5NLSEEAAAA/9k=",
     "object": "moon"
   }'
@@ -107,6 +119,7 @@ curl -X POST https://api.moondream.ai/v1/caption \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,/9j//gAQTGF2YzYxLjE5LjEwMQD/2wBDAAg+Pkk+SVVVVVVVVWRdZGhoaGRkZGRoaGhwcHCDg4NwcHBoaHBwfHyDg4+Tj4eHg4eTk5ubm7q6srLZ2eD/////xABZAAADAQEBAQAAAAAAAAAAAAAABgcFCAECAQEAAAAAAAAAAAAAAAAAAAAAEAADAAMBAQEBAAAAAAAAAAAAAQIDIREEURKBEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAGQAZAwESAAISAAMSAP/aAAwDAQACEQMRAD8A5/PQAAABirHyVS2mUip/Pm4/vQAih9ABuRUrVLqMEALVNead7/pFgAfc+d5NLSEEAAAA/9k=",
     "length": "normal",
     "stream": false
@@ -138,6 +151,7 @@ curl -X POST https://api.moondream.ai/v1/segment \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,...",
     "object": "cat"
   }'
@@ -158,4 +172,3 @@ curl -X POST https://api.moondream.ai/v1/segment \
 
   </TabItem>
 </Tabs>
-
diff --git a/docs/batch.md b/docs/batch.md
index ec2c5aa..f4d29bd 100644
--- a/docs/batch.md
+++ b/docs/batch.md
@@ -9,6 +9,8 @@ The Batch API lets you process large volumes of images asynchronously. Upload a
 
 **Pricing:** Batch API requests are billed at **50% off** standard API pricing. When using finetuned models, batch pricing is 50% off finetune pricing. See [pricing](https://moondream.ai/pricing) for details.
 
+Each batch runs on a single model selected when you complete the upload. Set `model` to `moondream3.1-9B-A2B`, `moondream3-preview`, or a saved `moondream3-preview/{finetune_id}@{step}` checkpoint.
+
 ## When to use Batch API
 
 - Processing thousands to 100,000 images
@@ -80,7 +82,7 @@ done
 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}")
+  -d "{\"parts\": $PARTS, \"model\": \"moondream3.1-9B-A2B\"}")
 
 BATCH_ID=$(echo $BATCH | jq -r '.id')
 echo "Batch submitted: $BATCH_ID"
@@ -119,7 +121,7 @@ with open("batch_input.jsonl", "rb") as f:
 batch = requests.post(
     f"{BASE_URL}/{file_id}?action=mpu-complete&uploadId={upload_id}",
     headers=headers,
-    json={"parts": parts}
+    json={"parts": parts, "model": "moondream3.1-9B-A2B"}
 ).json()
 
 print(f"Batch submitted: {batch['id']}")
@@ -169,7 +171,7 @@ const batch = await fetch(
   {
     method: 'POST',
     headers: { ...headers, 'Content-Type': 'application/json' },
-    body: JSON.stringify({ parts })
+    body: JSON.stringify({ parts, model: 'moondream3.1-9B-A2B' })
   }
 ).then(r => r.json());
 
@@ -229,7 +231,7 @@ while (true) {
 {
   "id": "01JQXYZ9ABCDEF123456",
   "status": "processing",
-  "model": "moondream3-preview",
+  "model": "moondream3.1-9B-A2B",
   "progress": { "total": 1000, "completed": 450 },
   "created_at": "2025-01-10T12:00:00Z"
 }
@@ -240,7 +242,7 @@ while (true) {
 {
   "id": "01JQXYZ9ABCDEF123456",
   "status": "completed",
-  "model": "moondream3-preview",
+  "model": "moondream3.1-9B-A2B",
   "progress": { "total": 1000, "completed": 998, "failed": 2 },
   "usage": { "input_tokens": 1500000, "output_tokens": 50000 },
   "outputs": [
@@ -399,14 +401,14 @@ Content-Type: application/json
   "parts": [
     { "partNumber": 1, "etag": "\"abc123...\"" }
   ],
-  "model": "moondream3-preview/finetune_id@step"
+  "model": "moondream3.1-9B-A2B"
 }
 ```
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `parts` | array | Yes | Array of uploaded parts with `partNumber` and `etag` |
-| `model` | string | No | Model to use. Default: `moondream3-preview`. For finetunes: `moondream3-preview/finetune_id@step` |
+| `model` | string | Yes | Model ID: `moondream3.1-9B-A2B`, `moondream3-preview`, or `moondream3-preview/finetune_id@step` |
 
 **Response:**
 ```json
@@ -471,7 +473,7 @@ GET /v1/batch/:batchId
 
 | Code | Description |
 |------|-------------|
-| `invalid_model` | Model format invalid (must be `moondream3-preview` or `moondream3-preview/finetune_id@step`) |
+| `invalid_model` | Model format invalid (must be `moondream3.1-9B-A2B`, `moondream3-preview`, or `moondream3-preview/finetune_id@step`) |
 | `validation_error` | Invalid JSONL, blank lines, or bad UTF-8 |
 | `limit_exceeded` | File or line limits exceeded |
 | `empty_batch` | No valid lines in file |
@@ -489,7 +491,7 @@ GET /v1/batch/:batchId
 
 ## Using finetuned models
 
-You can run batch jobs using your finetuned models by specifying the `model` parameter when completing the upload:
+You can run batch jobs using your finetuned models by specifying a `moondream3-preview` checkpoint in the `model` parameter when completing the upload:
 
 ```bash
 curl -s -X POST "https://api.moondream.ai/v1/batch/$FILE_ID?action=mpu-complete&uploadId=$UPLOAD_ID" \
diff --git a/docs/finetuning/http-api-reference.mdx b/docs/finetuning/http-api-reference.mdx
index 1185601..371369a 100644
--- a/docs/finetuning/http-api-reference.mdx
+++ b/docs/finetuning/http-api-reference.mdx
@@ -574,7 +574,7 @@ Results are ordered by step (ascending). Only saved checkpoints are returned.
 
 ---
 
-## POST /finetunes/:finetuneId/checkpoints/save
+## POST /finetunes/:finetuneId/checkpoints/save {#save-checkpoint}
 
 Save the current checkpoint and make it visible in the dashboard. The server resolves the
 current step for the finetune.
@@ -661,7 +661,8 @@ The `model` parameter is supported on the following inference endpoints:
 
 ### Notes
 
-- The `model` parameter is optional. If omitted, requests use the base `moondream3-preview` model.
+- Include the `model` parameter on inference requests.
 - Only saved checkpoints can be used for inference. Use `POST /finetunes/:finetuneId/checkpoints/save` to save a checkpoint first.
 - Both the `finetune_id` and `step` are required in the model string.
+- Finetuned checkpoints are only supported for `moondream3-preview`; `moondream3.1-9B-A2B` does not support finetunes.
 - Finetune inference is only available for authenticated API requests (not available in playground mode).
diff --git a/docs/openai.md b/docs/openai.md
index 37d5446..b14d3a3 100644
--- a/docs/openai.md
+++ b/docs/openai.md
@@ -8,7 +8,7 @@ Moondream Cloud exposes an **OpenAI-compatible** chat endpoint at `/v1/chat/comp
 
 ## Setup
 
-Use the OpenAI base URL `https://api.moondream.ai/v1`, your Moondream API key as the bearer token, and `moondream/moondream3-preview` as the model (the `moondream/` prefix is optional for this first-party model, so `moondream3-preview` also works). Grab a key from the [Moondream Cloud Console](https://moondream.ai/c/cloud/api-keys).
+Use the OpenAI base URL `https://api.moondream.ai/v1`, your Moondream API key as the bearer token, and set `model` to one of the supported Moondream model IDs. The examples below use `moondream3.1-9B-A2B`. Grab a key from the [Moondream Cloud Console](https://moondream.ai/c/cloud/api-keys).
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -25,7 +25,7 @@ client = OpenAI(
 )
 
 response = client.chat.completions.create(
-    model="moondream/moondream3-preview",
+    model="moondream3.1-9B-A2B",
     messages=[{"role": "user", "content": "What is 2 + 2?"}],
 )
 print(response.choices[0].message.content)
@@ -43,7 +43,7 @@ const client = new OpenAI({
 });
 
 const response = await client.chat.completions.create({
-  model: "moondream/moondream3-preview",
+  model: "moondream3.1-9B-A2B",
   messages: [{ role: "user", content: "What is 2 + 2?" }],
 });
 console.log(response.choices[0].message.content);
@@ -57,7 +57,7 @@ curl https://api.moondream.ai/v1/chat/completions \
   -H 'Authorization: Bearer YOUR_API_KEY' \
   -H 'Content-Type: application/json' \
   -d '{
-    "model": "moondream/moondream3-preview",
+    "model": "moondream3.1-9B-A2B",
     "messages": [{"role": "user", "content": "What is 2 + 2?"}]
   }'
 ```
@@ -79,7 +79,7 @@ with open("image.jpg", "rb") as f:
     data_url = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()
 
 response = client.chat.completions.create(
-    model="moondream/moondream3-preview",
+    model="moondream3.1-9B-A2B",
     messages=[{
         "role": "user",
         "content": [
@@ -99,7 +99,7 @@ curl https://api.moondream.ai/v1/chat/completions \
   -H 'Authorization: Bearer YOUR_API_KEY' \
   -H 'Content-Type: application/json' \
   -d '{
-    "model": "moondream/moondream3-preview",
+    "model": "moondream3.1-9B-A2B",
     "messages": [{
       "role": "user",
       "content": [
@@ -119,7 +119,7 @@ Send the full message history — earlier turns are kept as context.
 
 ```python
 response = client.chat.completions.create(
-    model="moondream/moondream3-preview",
+    model="moondream3.1-9B-A2B",
     messages=[
         {"role": "user", "content": "My name is Alice."},
         {"role": "assistant", "content": "Nice to meet you, Alice!"},
@@ -135,7 +135,7 @@ Set `stream=True` to receive the response as Server-Sent Events.
 
 ```python
 stream = client.chat.completions.create(
-    model="moondream/moondream3-preview",
+    model="moondream3.1-9B-A2B",
     messages=[{"role": "user", "content": "Write a short poem about the moon."}],
     stream=True,
 )
@@ -149,7 +149,7 @@ By default a stream does not include token usage. To receive it, set `stream_opt
 
 ```python
 stream = client.chat.completions.create(
-    model="moondream/moondream3-preview",
+    model="moondream3.1-9B-A2B",
     messages=[{"role": "user", "content": "Hello!"}],
     stream=True,
     stream_options={"include_usage": True},
@@ -165,7 +165,7 @@ Moondream 3 can produce an explicit reasoning trace before its answer. Enable it
 
 ```python
 response = client.chat.completions.create(
-    model="moondream/moondream3-preview",
+    model="moondream3.1-9B-A2B",
     messages=[{"role": "user", "content": "If I have 5 apples and give away 2, how many are left?"}],
     extra_body={"reasoning": True},
 )
@@ -180,7 +180,7 @@ See [Reasoning](/reasoning) for more on how Moondream 3 reasons.
 
 | Parameter | Type | Notes |
 |---|---|---|
-| `model` | string | `moondream/moondream3-preview`. See [Models](#models) for the available list. |
+| `model` | string | Required. Supported values: `moondream3.1-9B-A2B` or `moondream3-preview`. |
 | `messages` | array | OpenAI chat messages. `content` may be a string or an array of `text` / `image_url` parts. |
 | `temperature` | number | Sampling temperature. |
 | `top_p` | number | Nucleus sampling. |
@@ -199,3 +199,10 @@ List the available models with the standard OpenAI models endpoint:
 curl https://api.moondream.ai/v1/models \
   -H 'Authorization: Bearer YOUR_API_KEY'
 ```
+
+Public model IDs:
+
+| Model | Notes |
+|-------|-------|
+| `moondream3.1-9B-A2B` | Moondream 3.1 model. |
+| `moondream3-preview` | Moondream 3 Preview model. |
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 03ceeef..3029620 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -18,6 +18,7 @@ curl -X POST https://api.moondream.ai/v1/query \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "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?"
   }'
@@ -41,6 +42,7 @@ curl -X POST https://api.moondream.ai/v1/detect \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,/9j//gAQTGF2YzYxLjE5LjEwMQD/2wBDAAg+Pkk+SVVVVVVVVWRdZGhoaGRkZGRoaGhwcHCDg4NwcHBoaHBwfHyDg4+Tj4eHg4eTk5ubm7q6srLZ2eD/////xABZAAADAQEBAQAAAAAAAAAAAAAABgcFCAECAQEAAAAAAAAAAAAAAAAAAAAAEAADAAMBAQEBAAAAAAAAAAAAAQIDIREEURKBEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAGQAZAwESAAISAAMSAP/aAAwDAQACEQMRAD8A5/PQAAABirHyVS2mUip/Pm4/vQAih9ABuRUrVLqMEALVNead7/pFgAfc+d5NLSEEAAAA/9k=",
     "object": "moon"
   }'
@@ -71,6 +73,7 @@ curl -X POST https://api.moondream.ai/v1/point \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,/9j//gAQTGF2YzYxLjE5LjEwMQD/2wBDAAg+Pkk+SVVVVVVVVWRdZGhoaGRkZGRoaGhwcHCDg4NwcHBoaHBwfHyDg4+Tj4eHg4eTk5ubm7q6srLZ2eD/////xABZAAADAQEBAQAAAAAAAAAAAAAABgcFCAECAQEAAAAAAAAAAAAAAAAAAAAAEAADAAMBAQEBAAAAAAAAAAAAAQIDIREEURKBEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAGQAZAwESAAISAAMSAP/aAAwDAQACEQMRAD8A5/PQAAABirHyVS2mUip/Pm4/vQAih9ABuRUrVLqMEALVNead7/pFgAfc+d5NLSEEAAAA/9k=",
     "object": "moon"
   }'
@@ -99,6 +102,7 @@ curl -X POST https://api.moondream.ai/v1/caption \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,/9j//gAQTGF2YzYxLjE5LjEwMQD/2wBDAAg+Pkk+SVVVVVVVVWRdZGhoaGRkZGRoaGhwcHCDg4NwcHBoaHBwfHyDg4+Tj4eHg4eTk5ubm7q6srLZ2eD/////xABZAAADAQEBAQAAAAAAAAAAAAAABgcFCAECAQEAAAAAAAAAAAAAAAAAAAAAEAADAAMBAQEBAAAAAAAAAAAAAQIDIREEURKBEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAGQAZAwESAAISAAMSAP/aAAwDAQACEQMRAD8A5/PQAAABirHyVS2mUip/Pm4/vQAih9ABuRUrVLqMEALVNead7/pFgAfc+d5NLSEEAAAA/9k=",
     "length": "normal",
     "stream": false
diff --git a/docs/reasoning.md b/docs/reasoning.md
index 9bcc040..9973939 100644
--- a/docs/reasoning.md
+++ b/docs/reasoning.md
@@ -8,6 +8,7 @@ curl -X POST https://api.moondream.ai/v1/query \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "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?",
     "reasoning": true
@@ -76,4 +77,3 @@ console.log(result.answer);
 
   </TabItem>
 </Tabs>
-
diff --git a/docs/skills/caption.md b/docs/skills/caption.md
index e004282..e57423a 100644
--- a/docs/skills/caption.md
+++ b/docs/skills/caption.md
@@ -89,6 +89,7 @@ curl -X POST https://api.moondream.ai/v1/caption \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,...",
     "length": "normal",
     "stream": false
@@ -99,6 +100,7 @@ curl -X POST https://api.moondream.ai/v1/caption \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,...",
     "length": "short",
     "stream": false
@@ -109,6 +111,7 @@ curl -X POST https://api.moondream.ai/v1/caption \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,...",
     "length": "normal",
     "stream": true
@@ -143,6 +146,15 @@ For streaming responses, you'll receive a series of data events:
 - **"short"**: Brief 1-2 sentence summary (e.g., "A red car parked on a street.")
 - **"normal"** (default): Detailed description covering elements, context, colors, positioning, etc.
 
+## Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B`, `moondream3-preview`, or a `moondream3-preview/{finetune_id}@{step}` checkpoint. |
+| `image_url` | string | Yes | Base64 data URL for the input image. |
+| `length` | string | Yes | Caption length: `short`, `normal`, or `long`. |
+| `stream` | boolean | No | Stream caption chunks as Server-Sent Events. |
+
 ## Use Cases
 
 - Generating alt text for accessibility
diff --git a/docs/skills/detect.md b/docs/skills/detect.md
index d2da806..24e03a9 100644
--- a/docs/skills/detect.md
+++ b/docs/skills/detect.md
@@ -104,6 +104,7 @@ curl -X POST https://api.moondream.ai/v1/detect \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,...",
     "object": "person"
   }'
@@ -128,6 +129,14 @@ curl -X POST https://api.moondream.ai/v1/detect \
 }
 ```
 
+## Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B`, `moondream3-preview`, or a `moondream3-preview/{finetune_id}@{step}` checkpoint. |
+| `image_url` | string | Yes | Base64 data URL for the input image. |
+| `object` | string | Yes | Object or visual phrase to detect. |
+
 ## Common Object Types
 
 Moondream can detect a wide range of objects:
diff --git a/docs/skills/point.md b/docs/skills/point.md
index 5ab3e7b..5011577 100644
--- a/docs/skills/point.md
+++ b/docs/skills/point.md
@@ -92,6 +92,7 @@ curl -X POST https://api.moondream.ai/v1/point \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,...",
     "object": "face"
   }'
@@ -114,6 +115,14 @@ curl -X POST https://api.moondream.ai/v1/point \
 }
 ```
 
+## Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B`, `moondream3-preview`, or a `moondream3-preview/{finetune_id}@{step}` checkpoint. |
+| `image_url` | string | Yes | Base64 data URL for the input image. |
+| `object` | string | Yes | Object or visual phrase to locate. |
+
 ## Point vs. Detect
 
 - `/point` returns center coordinates only (x, y)
diff --git a/docs/skills/query.md b/docs/skills/query.md
index cfa4a05..f3ce86d 100644
--- a/docs/skills/query.md
+++ b/docs/skills/query.md
@@ -80,6 +80,7 @@ curl -X POST https://api.moondream.ai/v1/query \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,...",
     "question": "What is in this image?"
   }'
@@ -97,6 +98,16 @@ curl -X POST https://api.moondream.ai/v1/query \
 }
 ```
 
+## Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B`, `moondream3-preview`, or a `moondream3-preview/{finetune_id}@{step}` checkpoint. |
+| `image_url` | string | Yes | Base64 data URL for the input image. |
+| `question` | string | Yes | Question to answer about the image. |
+| `reasoning` | boolean | No | Enable reasoning trace for non-streaming requests. |
+| `stream` | boolean | No | Stream answer chunks as Server-Sent Events. |
+
 ## Best Practices
 
 - Ask specific questions rather than general ones
diff --git a/docs/skills/segment.md b/docs/skills/segment.md
index aaa42e4..96ce1a8 100644
--- a/docs/skills/segment.md
+++ b/docs/skills/segment.md
@@ -73,6 +73,7 @@ curl -X POST https://api.moondream.ai/v1/segment \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,...",
     "object": "cat"
   }'
@@ -95,6 +96,16 @@ curl -X POST https://api.moondream.ai/v1/segment \
 }
 ```
 
+## Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B` or `moondream3-preview`. Finetuned checkpoints are not supported for segmentation. |
+| `image_url` | string | Yes | Base64 data URL for the input image. |
+| `object` | string | Yes | Object or visual phrase to segment. |
+| `spatial_refs` | array | No | Optional normalized point or bounding box hints. |
+| `stream` | boolean | No | Stream bounding box and path updates as Server-Sent Events. |
+
 ## Spatial References
 
 You can guide the segmentation by providing spatial references - either points or bounding boxes with normalized coordinates (0-1):
@@ -148,6 +159,7 @@ curl -N -X POST https://api.moondream.ai/v1/segment \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "image_url": "data:image/jpeg;base64,...",
     "object": "cat",
     "stream": true
diff --git a/docs/streaming.md b/docs/streaming.md
index eb8d806..f6962e7 100644
--- a/docs/streaming.md
+++ b/docs/streaming.md
@@ -13,6 +13,7 @@ curl -N -X POST https://api.moondream.ai/v1/query \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
   -d '{
+    "model": "moondream3.1-9B-A2B",
     "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?",
     "stream": true
@@ -171,4 +172,3 @@ for await (const update of stream) {
 
   </TabItem>
 </Tabs>
-
diff --git a/src/components/RateLimitsTable.tsx b/src/components/RateLimitsTable.tsx
index 80402e4..7374a95 100644
--- a/src/components/RateLimitsTable.tsx
+++ b/src/components/RateLimitsTable.tsx
@@ -11,6 +11,26 @@ export default function RateLimitsTable() {
                 </div>
 
                 <div className={styles.tableBody}>
+                    <div className={styles.row}>
+                        <div className={styles.cell}>
+                            <span className={styles.modelName}>moondream3.1-9B-A2B</span>
+                        </div>
+                        <div className={styles.cell}>
+                            <div>
+                                <span className={styles.rateValue}>2</span>
+                                <span className={styles.rateUnit}>req/sec</span>
+                            </div>
+                            <div className={styles.tierNote}>Default for all API keys</div>
+                        </div>
+                        <div className={styles.cell}>
+                            <div>
+                                <span className={styles.rateValue}>10</span>
+                                <span className={styles.rateUnit}>req/sec</span>
+                            </div>
+                            <div className={styles.tierNote}>≥ $10 account balance</div>
+                        </div>
+                    </div>
+
                     <div className={styles.row}>
                         <div className={styles.cell}>
                             <span className={styles.modelName}>moondream3-preview</span>
@@ -35,4 +55,3 @@ export default function RateLimitsTable() {
         </div>
     );
 }
-

From 324f6790b12dc86cc190b2a3958aa12ade9b2fc7 Mon Sep 17 00:00:00 2001
From: Vikhyat Korrapati <vikhyatk@gmail.com>
Date: Tue, 7 Jul 2026 20:34:44 -0700
Subject: [PATCH 2/3] Address docs review comments

---
 docs/reasoning.md      | 2 +-
 docs/skills/caption.md | 2 +-
 docs/streaming.md      | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/reasoning.md b/docs/reasoning.md
index 9973939..e81e2d6 100644
--- a/docs/reasoning.md
+++ b/docs/reasoning.md
@@ -3,7 +3,7 @@ id: reasoning
 slug: /reasoning
 title: Reasoning
 ---
-```bash {7}
+```bash {8}
 curl -X POST https://api.moondream.ai/v1/query \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \
diff --git a/docs/skills/caption.md b/docs/skills/caption.md
index e57423a..0b06677 100644
--- a/docs/skills/caption.md
+++ b/docs/skills/caption.md
@@ -152,7 +152,7 @@ For streaming responses, you'll receive a series of data events:
 |-------|------|----------|-------------|
 | `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B`, `moondream3-preview`, or a `moondream3-preview/{finetune_id}@{step}` checkpoint. |
 | `image_url` | string | Yes | Base64 data URL for the input image. |
-| `length` | string | Yes | Caption length: `short`, `normal`, or `long`. |
+| `length` | string | No | Caption length: `short`, `normal`, or `long`. Defaults to `normal`. |
 | `stream` | boolean | No | Stream caption chunks as Server-Sent Events. |
 
 ## Use Cases
diff --git a/docs/streaming.md b/docs/streaming.md
index f6962e7..5dca0a9 100644
--- a/docs/streaming.md
+++ b/docs/streaming.md
@@ -8,7 +8,7 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import StreamingDemo from '@site/src/components/StreamingDemo';
 
-```bash {7}
+```bash {8}
 curl -N -X POST https://api.moondream.ai/v1/query \
   -H 'Content-Type: application/json' \
   -H 'X-Moondream-Auth: YOUR_API_KEY' \

From 18a08e81045f536249dfb90192f24446326249c0 Mon Sep 17 00:00:00 2001
From: Vikhyat Korrapati <vikhyatk@gmail.com>
Date: Tue, 7 Jul 2026 21:11:07 -0700
Subject: [PATCH 3/3] Generalize finetune checkpoint docs

---
 docs/api.md                            |  7 ++++---
 docs/batch.md                          | 13 +++++++------
 docs/finetuning/http-api-reference.mdx |  5 ++---
 docs/skills/caption.md                 |  2 +-
 docs/skills/detect.md                  |  2 +-
 docs/skills/point.md                   |  2 +-
 docs/skills/query.md                   |  2 +-
 docs/skills/segment.md                 |  2 +-
 8 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index e41ba43..76b997e 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -15,12 +15,13 @@ Prefer an OpenAI-style chat interface? Moondream also offers an [OpenAI-compatib
 
 ### Model selection
 
-Every direct API request must include a `model` field. Supported model IDs:
+Every direct API request must include a `model` field. Supported model values:
 
 | Model | Notes |
 |-------|-------|
-| `moondream3.1-9B-A2B` | Moondream 3.1 model. Finetuned checkpoints are not supported. |
-| `moondream3-preview` | Moondream 3 Preview model. Use this for finetuned checkpoints with `moondream3-preview/{finetune_id}@{step}`. |
+| `moondream3.1-9B-A2B` | Moondream 3.1 model. |
+| `moondream3-preview` | Moondream 3 Preview model. |
+| `{base_model}/{finetune_id}@{step}` | Saved finetuned checkpoint. |
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
diff --git a/docs/batch.md b/docs/batch.md
index f4d29bd..a1e7edd 100644
--- a/docs/batch.md
+++ b/docs/batch.md
@@ -9,7 +9,7 @@ The Batch API lets you process large volumes of images asynchronously. Upload a
 
 **Pricing:** Batch API requests are billed at **50% off** standard API pricing. When using finetuned models, batch pricing is 50% off finetune pricing. See [pricing](https://moondream.ai/pricing) for details.
 
-Each batch runs on a single model selected when you complete the upload. Set `model` to `moondream3.1-9B-A2B`, `moondream3-preview`, or a saved `moondream3-preview/{finetune_id}@{step}` checkpoint.
+Each batch runs on a single model selected when you complete the upload. Set `model` to a base model ID such as `moondream3.1-9B-A2B` or `moondream3-preview`, or to a saved finetuned checkpoint in `{base_model}/{finetune_id}@{step}` format.
 
 ## When to use Batch API
 
@@ -408,7 +408,7 @@ Content-Type: application/json
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `parts` | array | Yes | Array of uploaded parts with `partNumber` and `etag` |
-| `model` | string | Yes | Model ID: `moondream3.1-9B-A2B`, `moondream3-preview`, or `moondream3-preview/finetune_id@step` |
+| `model` | string | Yes | Model ID or saved checkpoint, e.g. `moondream3.1-9B-A2B`, `moondream3-preview`, or `{base_model}/finetune_id@step` |
 
 **Response:**
 ```json
@@ -473,7 +473,7 @@ GET /v1/batch/:batchId
 
 | Code | Description |
 |------|-------------|
-| `invalid_model` | Model format invalid (must be `moondream3.1-9B-A2B`, `moondream3-preview`, or `moondream3-preview/finetune_id@step`) |
+| `invalid_model` | Model format invalid (must be a supported base model ID or saved checkpoint in `{base_model}/finetune_id@step` format) |
 | `validation_error` | Invalid JSONL, blank lines, or bad UTF-8 |
 | `limit_exceeded` | File or line limits exceeded |
 | `empty_batch` | No valid lines in file |
@@ -491,7 +491,7 @@ GET /v1/batch/:batchId
 
 ## Using finetuned models
 
-You can run batch jobs using your finetuned models by specifying a `moondream3-preview` checkpoint in the `model` parameter when completing the upload:
+You can run batch jobs using your finetuned models by specifying a saved checkpoint in the `model` parameter when completing the upload:
 
 ```bash
 curl -s -X POST "https://api.moondream.ai/v1/batch/$FILE_ID?action=mpu-complete&uploadId=$UPLOAD_ID" \
@@ -499,11 +499,12 @@ curl -s -X POST "https://api.moondream.ai/v1/batch/$FILE_ID?action=mpu-complete&
   -H "Content-Type: application/json" \
   -d '{
     "parts": [...],
-    "model": "moondream3-preview/YOUR_FINETUNE_ID@STEP"
+    "model": "{base_model}/YOUR_FINETUNE_ID@STEP"
   }'
 ```
 
-The model format is `moondream3-preview/finetune_id@step`, where:
+The model format is `{base_model}/finetune_id@step`, where:
+- `base_model` is the model family used for the finetune
 - `finetune_id` is your finetune's ID (e.g., `01JQXYZ...`)
 - `step` is the checkpoint step number
 
diff --git a/docs/finetuning/http-api-reference.mdx b/docs/finetuning/http-api-reference.mdx
index 371369a..0f6768b 100644
--- a/docs/finetuning/http-api-reference.mdx
+++ b/docs/finetuning/http-api-reference.mdx
@@ -625,7 +625,7 @@ Once you have saved a checkpoint, you can use it for inference by specifying the
 ### Model format
 
 ```
-moondream3-preview/{finetune_id}@{step}
+{base_model}/{finetune_id}@{step}
 ```
 
 For example, if your finetune ID is `01HXYZ...` and you saved a checkpoint at step 500:
@@ -663,6 +663,5 @@ The `model` parameter is supported on the following inference endpoints:
 
 - Include the `model` parameter on inference requests.
 - Only saved checkpoints can be used for inference. Use `POST /finetunes/:finetuneId/checkpoints/save` to save a checkpoint first.
-- Both the `finetune_id` and `step` are required in the model string.
-- Finetuned checkpoints are only supported for `moondream3-preview`; `moondream3.1-9B-A2B` does not support finetunes.
+- The `base_model`, `finetune_id`, and `step` are required in the model string.
 - Finetune inference is only available for authenticated API requests (not available in playground mode).
diff --git a/docs/skills/caption.md b/docs/skills/caption.md
index 0b06677..7979c38 100644
--- a/docs/skills/caption.md
+++ b/docs/skills/caption.md
@@ -150,7 +150,7 @@ For streaming responses, you'll receive a series of data events:
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B`, `moondream3-preview`, or a `moondream3-preview/{finetune_id}@{step}` checkpoint. |
+| `model` | string | Yes | Model ID. Supported values include `moondream3.1-9B-A2B`, `moondream3-preview`, or a saved finetuned checkpoint in `{base_model}/{finetune_id}@{step}` format. |
 | `image_url` | string | Yes | Base64 data URL for the input image. |
 | `length` | string | No | Caption length: `short`, `normal`, or `long`. Defaults to `normal`. |
 | `stream` | boolean | No | Stream caption chunks as Server-Sent Events. |
diff --git a/docs/skills/detect.md b/docs/skills/detect.md
index 24e03a9..9fe7453 100644
--- a/docs/skills/detect.md
+++ b/docs/skills/detect.md
@@ -133,7 +133,7 @@ curl -X POST https://api.moondream.ai/v1/detect \
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B`, `moondream3-preview`, or a `moondream3-preview/{finetune_id}@{step}` checkpoint. |
+| `model` | string | Yes | Model ID. Supported values include `moondream3.1-9B-A2B`, `moondream3-preview`, or a saved finetuned checkpoint in `{base_model}/{finetune_id}@{step}` format. |
 | `image_url` | string | Yes | Base64 data URL for the input image. |
 | `object` | string | Yes | Object or visual phrase to detect. |
 
diff --git a/docs/skills/point.md b/docs/skills/point.md
index 5011577..a603c3a 100644
--- a/docs/skills/point.md
+++ b/docs/skills/point.md
@@ -119,7 +119,7 @@ curl -X POST https://api.moondream.ai/v1/point \
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B`, `moondream3-preview`, or a `moondream3-preview/{finetune_id}@{step}` checkpoint. |
+| `model` | string | Yes | Model ID. Supported values include `moondream3.1-9B-A2B`, `moondream3-preview`, or a saved finetuned checkpoint in `{base_model}/{finetune_id}@{step}` format. |
 | `image_url` | string | Yes | Base64 data URL for the input image. |
 | `object` | string | Yes | Object or visual phrase to locate. |
 
diff --git a/docs/skills/query.md b/docs/skills/query.md
index f3ce86d..42665cc 100644
--- a/docs/skills/query.md
+++ b/docs/skills/query.md
@@ -102,7 +102,7 @@ curl -X POST https://api.moondream.ai/v1/query \
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B`, `moondream3-preview`, or a `moondream3-preview/{finetune_id}@{step}` checkpoint. |
+| `model` | string | Yes | Model ID. Supported values include `moondream3.1-9B-A2B`, `moondream3-preview`, or a saved finetuned checkpoint in `{base_model}/{finetune_id}@{step}` format. |
 | `image_url` | string | Yes | Base64 data URL for the input image. |
 | `question` | string | Yes | Question to answer about the image. |
 | `reasoning` | boolean | No | Enable reasoning trace for non-streaming requests. |
diff --git a/docs/skills/segment.md b/docs/skills/segment.md
index 96ce1a8..191b399 100644
--- a/docs/skills/segment.md
+++ b/docs/skills/segment.md
@@ -100,7 +100,7 @@ curl -X POST https://api.moondream.ai/v1/segment \
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `model` | string | Yes | Model ID. Supported values: `moondream3.1-9B-A2B` or `moondream3-preview`. Finetuned checkpoints are not supported for segmentation. |
+| `model` | string | Yes | Model ID. Supported values include `moondream3.1-9B-A2B` and `moondream3-preview`. |
 | `image_url` | string | Yes | Base64 data URL for the input image. |
 | `object` | string | Yes | Object or visual phrase to segment. |
 | `spatial_refs` | array | No | Optional normalized point or bounding box hints. |