Restructure inference docs (#2225)

* Break Inference page into several pages

* Make all inference code snippets testable and clean up

* Make more snippets testable

* Edits

* Document automatic query and passage prefix injection in Cloud Inference

Qdrant Cloud Inference silently applies model-specific prefixes (e.g.
"query: "/"passage: " for E5, BGE-style instruction prefix for BGE/mxbai/
Snowflake arctic-embed) so users don't need to manage them manually.
Add a section explaining this behavior, the idempotency guarantee, and
the scope (Qdrant-hosted models only; external providers handle their own).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Document short query optimization in Cloud Inference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update links

* Expand on external provider API key usage

* Add section about external provider API keys

* Default to header for external API keys

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/csharp.cs

@@ -5,28 +5,31 @@ public class Snippet
 {
 	public static async Task Run()
 	{
+		// @hide-start
 		var client = new QdrantClient(
 		  host: "xyz-example.qdrant.io",
 		  port: 6334,
 		  https: true,
 		  apiKey: "<your-api-key>"
 		);
+		// @hide-end
 
-		await client.UpsertAsync(
-		    collectionName: "{collection_name}",
-		    points: new List<PointStruct>
-		    {
-		        new()
+		using (RequestHeaders.Use("jina-api-key", "<YOUR_JINAAI_API_KEY>"))
+		    await client.UpsertAsync(
+		        collectionName: "{collection_name}",
+		        points: new List<PointStruct>
 		        {
-		            Id = 1,
-		            Vectors = new Document()
+		            new()
 		            {
-		                Model = "jinaai/jina-clip-v2",
-		                Text = "Mission to Mars",
-		                Options = { ["jina-api-key"] = "<YOUR_JINAAI_API_KEY>", ["dimensions"] = 512 },
+		                Id = 1,
+		                Vectors = new Image()
+		                {
+		                    Model = "jinaai/jina-clip-v2",
+		                    Image_ = "https://qdrant.tech/example.png",
+		                    Options = { ["dimensions"] = 512 },
+		                },
 		            },
-		        },
-		    }
-		);
+		        }
+		    );
 	}
 }

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/generated/csharp.md

@@ -2,27 +2,21 @@
 using Qdrant.Client;
 using Qdrant.Client.Grpc;
 
-var client = new QdrantClient(
-  host: "xyz-example.qdrant.io",
-  port: 6334,
-  https: true,
-  apiKey: "<your-api-key>"
-);
-
-await client.UpsertAsync(
-    collectionName: "{collection_name}",
-    points: new List<PointStruct>
-    {
-        new()
+using (RequestHeaders.Use("jina-api-key", "<YOUR_JINAAI_API_KEY>"))
+    await client.UpsertAsync(
+        collectionName: "{collection_name}",
+        points: new List<PointStruct>
         {
-            Id = 1,
-            Vectors = new Document()
+            new()
             {
-                Model = "jinaai/jina-clip-v2",
-                Text = "Mission to Mars",
-                Options = { ["jina-api-key"] = "<YOUR_JINAAI_API_KEY>", ["dimensions"] = 512 },
+                Id = 1,
+                Vectors = new Image()
+                {
+                    Model = "jinaai/jina-clip-v2",
+                    Image_ = "https://qdrant.tech/example.png",
+                    Options = { ["dimensions"] = 512 },
+                },
             },
-        },
-    }
-);
+        }
+    );
 ```

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/generated/go.md

@@ -5,14 +5,9 @@ import (
 	"github.com/qdrant/go-client/qdrant"
 )
 
-client, err := qdrant.NewClient(&qdrant.Config{
-	Host:   "xyz-example.qdrant.io",
-	Port:   6334,
-	APIKey: "<paste-your-api-key-here>",
-	UseTLS: true,
-})
+ctx := qdrant.WithHeader(context.Background(), "jina-api-key", "<YOUR_JINAAI_API_KEY>")
 
-client.Upsert(context.Background(), &qdrant.UpsertPoints{
+client.Upsert(ctx, &qdrant.UpsertPoints{
 	CollectionName: "{collection_name}",
 	Points: []*qdrant.PointStruct{
 		{
@@ -21,8 +16,7 @@ client.Upsert(context.Background(), &qdrant.UpsertPoints{
 				Model: "jinaai/jina-clip-v2",
 				Image: qdrant.NewValueString("https://qdrant.tech/example.png"),
 				Options: qdrant.NewValueMap(map[string]any{
-					"jina-api-key": "<YOUR_JINAAI_API_KEY>",
-					"dimensions":   512,
+					"dimensions": 512,
 				}),
 			}),
 		},

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/generated/java.md

@@ -3,20 +3,19 @@ import static io.qdrant.client.PointIdFactory.id;
 import static io.qdrant.client.ValueFactory.value;
 import static io.qdrant.client.VectorsFactory.vectors;
 
+import io.grpc.Context;
 import io.qdrant.client.QdrantClient;
 import io.qdrant.client.QdrantGrpcClient;
+import io.qdrant.client.RequestHeaders;
 import io.qdrant.client.grpc.Points.Image;
 import io.qdrant.client.grpc.Points.PointStruct;
 import java.util.List;
 import java.util.Map;
 
-QdrantClient client =
-    new QdrantClient(
-        QdrantGrpcClient.newBuilder("xyz-example.qdrant.io", 6334, true)
-            .withApiKey("<your-api-key")
-            .build());
+Context ctx = RequestHeaders.withHeader(
+    Context.current(), "jina-api-key", "<YOUR_JINAAI_API_KEY>");
 
-client
+ctx.call(() -> client
     .upsertAsync(
         "{collection_name}",
         List.of(
@@ -29,11 +28,9 @@ client
                             .setImage(value("https://qdrant.tech/example.png"))
                             .putAllOptions(
                                 Map.of(
-                                    "jina-api-key",
-                                    value("<YOUR_JINAAI_API_KEY>"),
                                     "dimensions",
                                     value(512)))
                             .build()))
                 .build()))
-    .get();
+    .get());
 ```

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/generated/python.md

@@ -1,26 +1,27 @@
 ```python
 from qdrant_client import QdrantClient, models
+from qdrant_client.context_headers import headers
 
 client = QdrantClient(
     url="https://xyz-example.qdrant.io:6333", 
-    api_key="<your-api-key>", 
+    api_key="<your-qdrant-api-key>",
     cloud_inference=True
 )
 
-client.upsert(
-    collection_name="{collection_name}",
-    points=[
-        models.PointStruct(
-            id=1,
-            vector=models.Image(
-                image="https://qdrant.tech/example.png",
-                model="jinaai/jina-clip-v2",
-                options={
-                    "jina-api-key": "<your_jinaai_api_key>",
-                    "dimensions": 512
-                }
+with headers({"jina-api-key": "<YOUR_JINAAI_API_KEY>"}):
+    client.upsert(
+        collection_name="{collection_name}",
+        points=[
+            models.PointStruct(
+                id=1,
+                vector=models.Image(
+                    image="https://qdrant.tech/example.png",
+                    model="jinaai/jina-clip-v2",
+                    options={
+                        "dimensions": 512
+                    }
+                )
             )
-        )
-    ]
-)
+        ]
+    )
 ```

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/generated/rust.md

@@ -5,12 +5,11 @@ use qdrant_client::{
 };
 use std::collections::HashMap;
 
-let client = Qdrant::from_url("<your-qdrant-url>").build()?;
 let mut options = HashMap::new();
-options.insert("jina-api-key".to_string(), "<YOUR_JINAAI_API_KEY>".into());
 options.insert("dimensions".to_string(), 512.into());
 
 client
+    .with_header("jina-api-key", "<YOUR_JINAAI_API_KEY>")
     .upsert_points(UpsertPointsBuilder::new("{collection_name}",
         vec![
             PointStruct::new(1,

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/generated/typescript.md

@@ -1,21 +1,20 @@
 ```typescript
-import { QdrantClient } from "@qdrant/js-client-rest";
+import { QdrantClient, withHeaders } from "@qdrant/js-client-rest";
 
-const client = new QdrantClient({ host: "localhost", port: 6333 });
-
-client.upsert("{collection_name}", {
-    points: [
-        {
-            id: 1,
-            vector: {
-                image: 'https://qdrant.tech/example.png',
-                model: 'jinaai/jina-clip-v2',
-                options: {
-                    'jina-api-key': '<your_jinaai_api_key>',
-                    dimensions: 512,
+await withHeaders({ 'jina-api-key': '<YOUR_JINAAI_API_KEY>' }, () =>
+    client.upsert("{collection_name}", {
+        points: [
+            {
+                id: 1,
+                vector: {
+                    image: 'https://qdrant.tech/example.png',
+                    model: 'jinaai/jina-clip-v2',
+                    options: {
+                        dimensions: 512,
+                    },
                 },
             },
-        },
-    ],
-});
+        ],
+    })
+);
 ```

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/go.go

@@ -7,16 +7,20 @@ import (
 )
 
 func Main() {
+	// @hide-start
 	client, err := qdrant.NewClient(&qdrant.Config{
 		Host:   "xyz-example.qdrant.io",
 		Port:   6334,
 		APIKey: "<paste-your-api-key-here>",
 		UseTLS: true,
 	})
+	// @hide-end
 
 	if err != nil { panic(err) } // @hide
 
-	client.Upsert(context.Background(), &qdrant.UpsertPoints{
+	ctx := qdrant.WithHeader(context.Background(), "jina-api-key", "<YOUR_JINAAI_API_KEY>")
+
+	client.Upsert(ctx, &qdrant.UpsertPoints{
 		CollectionName: "{collection_name}",
 		Points: []*qdrant.PointStruct{
 			{
@@ -25,8 +29,7 @@ func Main() {
 					Model: "jinaai/jina-clip-v2",
 					Image: qdrant.NewValueString("https://qdrant.tech/example.png"),
 					Options: qdrant.NewValueMap(map[string]any{
-						"jina-api-key": "<YOUR_JINAAI_API_KEY>",
-						"dimensions":   512,
+						"dimensions": 512,
 					}),
 				}),
 			},

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/java.java

@@ -4,8 +4,10 @@ import static io.qdrant.client.PointIdFactory.id;
 import static io.qdrant.client.ValueFactory.value;
 import static io.qdrant.client.VectorsFactory.vectors;
 
+import io.grpc.Context;
 import io.qdrant.client.QdrantClient;
 import io.qdrant.client.QdrantGrpcClient;
+import io.qdrant.client.RequestHeaders;
 import io.qdrant.client.grpc.Points.Image;
 import io.qdrant.client.grpc.Points.PointStruct;
 import java.util.List;
@@ -13,13 +15,18 @@ import java.util.Map;
 
 public class Snippet {
         public static void run() throws Exception {
+                // @hide-start
                 QdrantClient client =
                     new QdrantClient(
                         QdrantGrpcClient.newBuilder("xyz-example.qdrant.io", 6334, true)
                             .withApiKey("<your-api-key")
                             .build());
+                // @hide-end
 
-                client
+                Context ctx = RequestHeaders.withHeader(
+                    Context.current(), "jina-api-key", "<YOUR_JINAAI_API_KEY>");
+
+                ctx.call(() -> client
                     .upsertAsync(
                         "{collection_name}",
                         List.of(
@@ -32,12 +39,10 @@ public class Snippet {
                                             .setImage(value("https://qdrant.tech/example.png"))
                                             .putAllOptions(
                                                 Map.of(
-                                                    "jina-api-key",
-                                                    value("<YOUR_JINAAI_API_KEY>"),
                                                     "dimensions",
                                                     value(512)))
                                             .build()))
                                 .build()))
-                    .get();
+                    .get());
         }
 }

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/python.py

@@ -1,24 +1,25 @@
 from qdrant_client import QdrantClient, models
+from qdrant_client.context_headers import headers
 
 client = QdrantClient(
     url="https://xyz-example.qdrant.io:6333", 
-    api_key="<your-api-key>", 
+    api_key="<your-qdrant-api-key>",
     cloud_inference=True
 )
 
-client.upsert(
-    collection_name="{collection_name}",
-    points=[
-        models.PointStruct(
-            id=1,
-            vector=models.Image(
-                image="https://qdrant.tech/example.png",
-                model="jinaai/jina-clip-v2",
-                options={
-                    "jina-api-key": "<your_jinaai_api_key>",
-                    "dimensions": 512
-                }
+with headers({"jina-api-key": "<YOUR_JINAAI_API_KEY>"}):
+    client.upsert(
+        collection_name="{collection_name}",
+        points=[
+            models.PointStruct(
+                id=1,
+                vector=models.Image(
+                    image="https://qdrant.tech/example.png",
+                    model="jinaai/jina-clip-v2",
+                    options={
+                        "dimensions": 512
+                    }
+                )
             )
-        )
-    ]
-)
+        ]
+    )

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/rust.rs

@@ -5,12 +5,12 @@ use qdrant_client::{
 use std::collections::HashMap;
 
 pub async fn main() -> anyhow::Result<()> {
-    let client = Qdrant::from_url("<your-qdrant-url>").build()?;
+    let client = Qdrant::from_url("<your-qdrant-url>").build()?; // @hide
     let mut options = HashMap::new();
-    options.insert("jina-api-key".to_string(), "<YOUR_JINAAI_API_KEY>".into());
     options.insert("dimensions".to_string(), 512.into());
 
     client
+        .with_header("jina-api-key", "<YOUR_JINAAI_API_KEY>")
         .upsert_points(UpsertPointsBuilder::new("{collection_name}",
             vec![
                 PointStruct::new(1,

qdrant-landing/content/documentation/headless/snippets/inference/jinaai-upsert/typescript.ts

@@ -1,19 +1,20 @@
-import { QdrantClient } from "@qdrant/js-client-rest";
+import { QdrantClient, withHeaders } from "@qdrant/js-client-rest";
 
-const client = new QdrantClient({ host: "localhost", port: 6333 });
+const client = new QdrantClient({ host: "localhost", port: 6333 }); // @hide
 
-client.upsert("{collection_name}", {
-    points: [
-        {
-            id: 1,
-            vector: {
-                image: 'https://qdrant.tech/example.png',
-                model: 'jinaai/jina-clip-v2',
-                options: {
-                    'jina-api-key': '<your_jinaai_api_key>',
-                    dimensions: 512,
+await withHeaders({ 'jina-api-key': '<YOUR_JINAAI_API_KEY>' }, () =>
+    client.upsert("{collection_name}", {
+        points: [
+            {
+                id: 1,
+                vector: {
+                    image: 'https://qdrant.tech/example.png',
+                    model: 'jinaai/jina-clip-v2',
+                    options: {
+                        dimensions: 512,
+                    },
                 },
             },
-        },
-    ],
-});
+        ],
+    })
+);