Require explicit model_api_key for Python SDK

pirate · pirate · commit f57a6ea3ca3f · 2026-04-01T11:33:46.000-07:00
diff --git a/examples/local_example.py b/examples/local_example.py
@@ -51,6 +51,7 @@ def main() -> None:
 
     client = Stagehand(
         server="local",
+        model_api_key=model_key,
         local_ready_timeout_s=30.0,
     )
 
diff --git a/src/stagehand/_client.py b/src/stagehand/_client.py
@@ -24,7 +24,7 @@
 from ._models import FinalRequestOptions
 from ._version import __version__
 from ._streaming import Stream as Stream, AsyncStream as AsyncStream
-from ._exceptions import APIStatusError, StagehandError
+from ._exceptions import APIStatusError
 from ._base_client import (
     DEFAULT_MAX_RETRIES,
     SyncAPIClient,
@@ -47,42 +47,12 @@
     "AsyncClient",
 ]
 
-_MODEL_API_KEY_ENV_VARS: tuple[str, ...] = (
-    "MODEL_API_KEY",
-    "OPENAI_API_KEY",
-    "ANTHROPIC_API_KEY",
-    "GEMINI_API_KEY",
-    "GOOGLE_GENERATIVE_AI_API_KEY",
-    "GOOGLE_API_KEY",
-    "GOOGLE_VERTEX_AI_API_KEY",
-    "GROQ_API_KEY",
-    "CEREBRAS_API_KEY",
-    "TOGETHER_AI_API_KEY",
-    "MISTRAL_API_KEY",
-    "DEEPSEEK_API_KEY",
-    "PERPLEXITY_API_KEY",
-    "AZURE_API_KEY",
-    "XAI_API_KEY",
-)
-
-
-def _resolve_model_api_key(model_api_key: str | None) -> str | None:
-    if model_api_key is not None:
-        return model_api_key
-
-    for env_var in _MODEL_API_KEY_ENV_VARS:
-        value = os.environ.get(env_var)
-        if value:
-            return value
-
-    return None
-
 
 class Stagehand(SyncAPIClient):
     # client options
     browserbase_api_key: str | None
     browserbase_project_id: str | None
-    model_api_key: str
+    model_api_key: str | None
 
     def __init__(
         self,
@@ -97,7 +67,6 @@ def __init__(
         local_headless: bool = True,
         local_chrome_path: str | None = None,
         local_ready_timeout_s: float = 10.0,
-        local_openai_api_key: str | None = None,
         local_shutdown_on_close: bool = True,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = not_given,
@@ -123,7 +92,6 @@ def __init__(
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `browserbase_api_key` from `BROWSERBASE_API_KEY`
         - `browserbase_project_id` from `BROWSERBASE_PROJECT_ID`
-        - `model_api_key` from `MODEL_API_KEY` or a recognized provider API key env var
         """
         self._server_mode: Literal["remote", "local"] = server
         self._local_stagehand_binary_path = _local_stagehand_binary_path
@@ -132,7 +100,6 @@ def __init__(
         self._local_headless = local_headless
         self._local_chrome_path = local_chrome_path
         self._local_ready_timeout_s = local_ready_timeout_s
-        self._local_openai_api_key = local_openai_api_key
         self._local_shutdown_on_close = local_shutdown_on_close
 
         if browserbase_api_key is None:
@@ -143,12 +110,6 @@ def __init__(
         self.browserbase_api_key = browserbase_api_key
         self.browserbase_project_id = browserbase_project_id
 
-        model_api_key = _resolve_model_api_key(model_api_key)
-        if model_api_key is None:
-            raise StagehandError(
-                "The model_api_key client option must be set either by passing model_api_key to the client "
-                f"or by setting one of the supported environment variables: {', '.join(_MODEL_API_KEY_ENV_VARS)}"
-            )
         self.model_api_key = model_api_key
 
         self._sea_server: SeaServerManager | None = None
@@ -157,14 +118,13 @@ def __init__(
             if base_url is None:
                 base_url = "http://127.0.0.1"
 
-            local_model_api_key = local_openai_api_key or model_api_key
             self._sea_server = SeaServerManager(
                 config=SeaServerConfig(
                     host=local_host,
                     port=local_port,
                     headless=local_headless,
                     ready_timeout_s=local_ready_timeout_s,
-                    model_api_key=local_model_api_key,
+                    model_api_key=model_api_key,
                     chrome_path=local_chrome_path,
                     shutdown_on_close=local_shutdown_on_close,
                 ),
@@ -240,7 +200,7 @@ def _bb_project_id_auth(self) -> dict[str, str]:
     @property
     def _llm_model_api_key_auth(self) -> dict[str, str]:
         model_api_key = self.model_api_key
-        return {"x-model-api-key": model_api_key}
+        return {"x-model-api-key": model_api_key} if model_api_key else {}
 
     @property
     @override
@@ -266,7 +226,6 @@ def copy(
         local_headless: bool | None = None,
         local_chrome_path: str | None = None,
         local_ready_timeout_s: float | None = None,
-        local_openai_api_key: str | None = None,
         local_shutdown_on_close: bool | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = not_given,
@@ -313,9 +272,6 @@ def copy(
             local_ready_timeout_s=local_ready_timeout_s
             if local_ready_timeout_s is not None
             else self._local_ready_timeout_s,
-            local_openai_api_key=local_openai_api_key
-            if local_openai_api_key is not None
-            else self._local_openai_api_key,
             local_shutdown_on_close=local_shutdown_on_close
             if local_shutdown_on_close is not None
             else self._local_shutdown_on_close,
@@ -370,7 +326,7 @@ class AsyncStagehand(AsyncAPIClient):
     # client options
     browserbase_api_key: str | None
     browserbase_project_id: str | None
-    model_api_key: str
+    model_api_key: str | None
 
     def __init__(
         self,
@@ -385,7 +341,6 @@ def __init__(
         local_headless: bool = True,
         local_chrome_path: str | None = None,
         local_ready_timeout_s: float = 10.0,
-        local_openai_api_key: str | None = None,
         local_shutdown_on_close: bool = True,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = not_given,
@@ -411,7 +366,6 @@ def __init__(
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `browserbase_api_key` from `BROWSERBASE_API_KEY`
         - `browserbase_project_id` from `BROWSERBASE_PROJECT_ID`
-        - `model_api_key` from `MODEL_API_KEY` or a recognized provider API key env var
         """
         self._server_mode: Literal["remote", "local"] = server
         self._local_stagehand_binary_path = _local_stagehand_binary_path
@@ -420,7 +374,6 @@ def __init__(
         self._local_headless = local_headless
         self._local_chrome_path = local_chrome_path
         self._local_ready_timeout_s = local_ready_timeout_s
-        self._local_openai_api_key = local_openai_api_key
         self._local_shutdown_on_close = local_shutdown_on_close
 
         if browserbase_api_key is None:
@@ -431,27 +384,20 @@ def __init__(
         self.browserbase_api_key = browserbase_api_key
         self.browserbase_project_id = browserbase_project_id
 
-        model_api_key = _resolve_model_api_key(model_api_key)
-        if model_api_key is None:
-            raise StagehandError(
-                "The model_api_key client option must be set either by passing model_api_key to the client "
-                f"or by setting one of the supported environment variables: {', '.join(_MODEL_API_KEY_ENV_VARS)}"
-            )
         self.model_api_key = model_api_key
 
         self._sea_server: SeaServerManager | None = None
         if server == "local":
             if base_url is None:
                 base_url = "http://127.0.0.1"
 
-            local_model_api_key = local_openai_api_key or model_api_key
             self._sea_server = SeaServerManager(
                 config=SeaServerConfig(
                     host=local_host,
                     port=local_port,
                     headless=local_headless,
                     ready_timeout_s=local_ready_timeout_s,
-                    model_api_key=local_model_api_key,
+                    model_api_key=model_api_key,
                     chrome_path=local_chrome_path,
                     shutdown_on_close=local_shutdown_on_close,
                 ),
@@ -527,7 +473,7 @@ def _bb_project_id_auth(self) -> dict[str, str]:
     @property
     def _llm_model_api_key_auth(self) -> dict[str, str]:
         model_api_key = self.model_api_key
-        return {"x-model-api-key": model_api_key}
+        return {"x-model-api-key": model_api_key} if model_api_key else {}
 
     @property
     @override
@@ -553,7 +499,6 @@ def copy(
         local_headless: bool | None = None,
         local_chrome_path: str | None = None,
         local_ready_timeout_s: float | None = None,
-        local_openai_api_key: str | None = None,
         local_shutdown_on_close: bool | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = not_given,
@@ -600,9 +545,6 @@ def copy(
             local_ready_timeout_s=local_ready_timeout_s
             if local_ready_timeout_s is not None
             else self._local_ready_timeout_s,
-            local_openai_api_key=local_openai_api_key
-            if local_openai_api_key is not None
-            else self._local_openai_api_key,
             local_shutdown_on_close=local_shutdown_on_close
             if local_shutdown_on_close is not None
             else self._local_shutdown_on_close,
diff --git a/src/stagehand/lib/sea_server.py b/src/stagehand/lib/sea_server.py
@@ -127,8 +127,7 @@ def _build_process_env(self, *, port: int) -> dict[str, str]:
         proc_env["HOST"] = self._config.host
         proc_env["PORT"] = str(port)
         proc_env["HEADLESS"] = "true" if self._config.headless else "false"
-        if self._config.model_api_key:
-            proc_env["MODEL_API_KEY"] = self._config.model_api_key
+        proc_env["MODEL_API_KEY"] = self._config.model_api_key or ""
         if self._config.chrome_path:
             proc_env["CHROME_PATH"] = self._config.chrome_path
             proc_env["LIGHTHOUSE_CHROMIUM_PATH"] = self._config.chrome_path
diff --git a/tests/test_client.py b/tests/test_client.py
@@ -20,12 +20,11 @@
 from pydantic import ValidationError
 
 from stagehand import Stagehand, AsyncStagehand, APIResponseValidationError
-from stagehand._client import _MODEL_API_KEY_ENV_VARS
 from stagehand._types import Omit
 from stagehand._utils import asyncify
 from stagehand._models import BaseModel, FinalRequestOptions
 from stagehand._streaming import Stream, AsyncStream
-from stagehand._exceptions import APIStatusError, StagehandError, APITimeoutError, APIResponseValidationError
+from stagehand._exceptions import APIStatusError, APITimeoutError, APIResponseValidationError
 from stagehand._base_client import (
     DEFAULT_TIMEOUT,
     HTTPX_DEFAULT_TIMEOUT,
@@ -46,10 +45,6 @@
 model_api_key = "My Model API Key"
 
 
-def _omit_model_api_key_env_vars() -> dict[str, Omit]:
-    return {name: Omit() for name in _MODEL_API_KEY_ENV_VARS}
-
-
 def _get_params(client: BaseClient[Any, Any]) -> dict[str, str]:
     request = client._build_request(FinalRequestOptions(method="get", url="/foo"))
     url = httpx.URL(request.url)
@@ -469,51 +464,21 @@ def test_validate_headers(self) -> None:
         request = client._build_request(FinalRequestOptions(method="get", url="/foo"))
         assert request.headers.get("x-model-api-key") == model_api_key
 
-        with pytest.raises(StagehandError):
-            with update_env(
-                **{
-                    "BROWSERBASE_API_KEY": Omit(),
-                    "BROWSERBASE_PROJECT_ID": Omit(),
-                    **_omit_model_api_key_env_vars(),
-                }
-            ):
-                client2 = Stagehand(
-                    base_url=base_url,
-                    browserbase_api_key=None,
-                    browserbase_project_id=None,
-                    model_api_key=None,
-                    _strict_response_validation=True,
-                )
-                client2.sessions.start(model_name="openai/gpt-5-nano")
-
-    def test_model_api_key_falls_back_to_openai_env(self) -> None:
-        with update_env(
-            MODEL_API_KEY=Omit(),
-            OPENAI_API_KEY="openai-key",
-        ):
-            client = Stagehand(
-                base_url=base_url,
-                browserbase_api_key=browserbase_api_key,
-                browserbase_project_id=browserbase_project_id,
-                model_api_key=None,
-            )
-
-        assert client.model_api_key == "openai-key"
-
-    def test_model_api_key_falls_back_to_gemini_env(self) -> None:
         with update_env(
-            MODEL_API_KEY=Omit(),
-            OPENAI_API_KEY=Omit(),
-            GEMINI_API_KEY="gemini-key",
+            BROWSERBASE_API_KEY=Omit(),
+            BROWSERBASE_PROJECT_ID=Omit(),
         ):
-            client = Stagehand(
+            client2 = Stagehand(
                 base_url=base_url,
-                browserbase_api_key=browserbase_api_key,
-                browserbase_project_id=browserbase_project_id,
+                browserbase_api_key=None,
+                browserbase_project_id=None,
                 model_api_key=None,
+                _strict_response_validation=True,
             )
-
-        assert client.model_api_key == "gemini-key"
+            request = client2._build_request(FinalRequestOptions(method="get", url="/foo"))
+            assert request.headers.get("x-bb-api-key") is None
+            assert request.headers.get("x-bb-project-id") is None
+            assert request.headers.get("x-model-api-key") is None
 
     def test_default_query_option(self) -> None:
         client = Stagehand(
@@ -1546,51 +1511,21 @@ def test_validate_headers(self) -> None:
         request = client._build_request(FinalRequestOptions(method="get", url="/foo"))
         assert request.headers.get("x-model-api-key") == model_api_key
 
-        with pytest.raises(StagehandError):
-            with update_env(
-                **{
-                    "BROWSERBASE_API_KEY": Omit(),
-                    "BROWSERBASE_PROJECT_ID": Omit(),
-                    **_omit_model_api_key_env_vars(),
-                }
-            ):
-                client2 = AsyncStagehand(
-                    base_url=base_url,
-                    browserbase_api_key=None,
-                    browserbase_project_id=None,
-                    model_api_key=None,
-                    _strict_response_validation=True,
-                )
-            _ = client2
-
-    async def test_model_api_key_falls_back_to_openai_env(self) -> None:
-        with update_env(
-            MODEL_API_KEY=Omit(),
-            OPENAI_API_KEY="openai-key",
-        ):
-            client = AsyncStagehand(
-                base_url=base_url,
-                browserbase_api_key=browserbase_api_key,
-                browserbase_project_id=browserbase_project_id,
-                model_api_key=None,
-            )
-
-        assert client.model_api_key == "openai-key"
-
-    async def test_model_api_key_falls_back_to_gemini_env(self) -> None:
         with update_env(
-            MODEL_API_KEY=Omit(),
-            OPENAI_API_KEY=Omit(),
-            GEMINI_API_KEY="gemini-key",
+            BROWSERBASE_API_KEY=Omit(),
+            BROWSERBASE_PROJECT_ID=Omit(),
         ):
-            client = AsyncStagehand(
+            client2 = AsyncStagehand(
                 base_url=base_url,
-                browserbase_api_key=browserbase_api_key,
-                browserbase_project_id=browserbase_project_id,
+                browserbase_api_key=None,
+                browserbase_project_id=None,
                 model_api_key=None,
+                _strict_response_validation=True,
             )
-
-        assert client.model_api_key == "gemini-key"
+            request = client2._build_request(FinalRequestOptions(method="get", url="/foo"))
+            assert request.headers.get("x-bb-api-key") is None
+            assert request.headers.get("x-bb-project-id") is None
+            assert request.headers.get("x-model-api-key") is None
 
     async def test_default_query_option(self) -> None:
         client = AsyncStagehand(
diff --git a/tests/test_local_server.py b/tests/test_local_server.py

Original file line number	Diff line number	Diff line change
`@@ -51,6 +51,7 @@ def main() -> None:`
`51`	`51`
`52`	`52`	`client = Stagehand(`
`53`	`53`	`server="local",`
	`54`	`+ model_api_key=model_key,`
`54`	`55`	`local_ready_timeout_s=30.0,`
`55`	`56`	`)`
`56`	`57`