feat: add batch/files base URL seam (batch.api.voyageai.com)

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

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,