From 259b199d6ec4bc8320d583e3a36b4b7c48dc86c5 Mon Sep 17 00:00:00 2001
From: fzowl <zoltan@voyageai.com>
Date: Fri, 11 Sep 2026 12:55:58 +0200
Subject: [PATCH] feat: add batch/files base URL seam (batch.api.voyageai.com)

Batch and files APIs are served from a dedicated batch. subdomain
(https://batch.api.voyageai.com/v1) instead of the default host. Add
util.get_batch_base_url() deriving that host from the default base URL,
preserving the /v1 path and leaving the MongoDB host untouched. The
default base URL for all other endpoints is unchanged (non-breaking).
---
 tests/test_unit.py | 11 +++++++++++
 voyageai/util.py   | 18 ++++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/tests/test_unit.py b/tests/test_unit.py
index d3df830..8a4dceb 100644
--- a/tests/test_unit.py
+++ b/tests/test_unit.py
@@ -328,6 +328,17 @@ def test_get_default_base_url_voyage(self):
     def test_get_default_base_url_mongodb(self):
         assert util.get_default_base_url("al-abc") == "https://ai.mongodb.com/v1"
 
+    def test_get_batch_base_url_voyage(self):
+        assert util.get_batch_base_url("pa-abc") == "https://batch.api.voyageai.com/v1"
+
+    def test_get_batch_base_url_mongodb(self):
+        # The batch subdomain only applies to the Voyage AI host; MongoDB is left as-is.
+        assert util.get_batch_base_url("al-abc") == "https://ai.mongodb.com/v1"
+
+    def test_get_batch_base_url_leaves_default_unchanged(self):
+        # Batch host derivation must not mutate the default base URL for other endpoints.
+        assert util.get_default_base_url("pa-abc") == "https://api.voyageai.com/v1"
+
     def test_resolve_numpy_dtype(self):
         assert util._resolve_numpy_dtype(None) == np.float32
         assert util._resolve_numpy_dtype("float") == np.float32
diff --git a/voyageai/util.py b/voyageai/util.py
index b489223..f92d374 100644
--- a/voyageai/util.py
+++ b/voyageai/util.py
@@ -103,6 +103,24 @@ def get_default_base_url(api_key: str) -> str:
         return "https://api.voyageai.com/v1"
 
 
+def get_batch_base_url(api_key: str) -> str:
+    """Base URL for the batch and files APIs.
+
+    These endpoints are served from a dedicated ``batch.`` subdomain
+    (e.g. ``https://batch.api.voyageai.com/v1``) rather than the default host
+    used by embeddings, rerank, multimodal and contextualized embeddings. The
+    ``/v1`` path convention is preserved. This is not a breaking change: the
+    default base URL returned by :func:`get_default_base_url` is unchanged for
+    all other endpoints.
+
+    The MongoDB host (``al-`` keys) is left untouched, since the ``batch.``
+    subdomain only applies to the Voyage AI host.
+    """
+    return get_default_base_url(api_key).replace(
+        "https://api.voyageai.com", "https://batch.api.voyageai.com", 1
+    )
+
+
 def _resolve_numpy_dtype(dtype: Optional[str] = None) -> str:
     dtype_mapping = {
         None: np.float32,