Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

feat: add API Route provider preset

dennyho0917bdcb937e432e
diff --git a/docs/en/concepts/provider-system.md b/docs/en/concepts/provider-system.md
index c5c2629..5cadcf7 100644
--- a/docs/en/concepts/provider-system.md
+++ b/docs/en/concepts/provider-system.md
@@ -16,6 +16,7 @@ Hyper-Extract supports these ways to connect to LLMs: **OpenAI**, **Anthropic**,
| **DeepSeek** | deepseek-v4-flash / deepseek-v4-pro | ✅ | ✅ | OpenAI-compatible. V4 models default to "thinking" mode, which Hyper-Extract auto-disables (`extra_body`) so structured extraction works. LLM only — no embeddings API. Keys: `DEEPSEEK_API_KEY` |
| **OrcaRouter** | `orcarouter/auto`, `openai/gpt-4o-mini`, `anthropic/claude-haiku-4-5`, `deepseek/...`, `gemini/...` | ✅ | ✅ | OpenAI-compatible gateway routing 150+ models from OpenAI, Anthropic, Google, DeepSeek, Qwen, MiniMax, xAI behind one endpoint and key. Keys: `ORCAROUTER_API_KEY` |
| **Cheaper Inference** | gpt-5.4-mini | ✅ | ✅ | OpenAI-compatible gateway. One key gives access to models from several labs. LLM only — no embeddings API (pair with an OpenAI-compatible embedder). Keys: `CHEAPER_INFERENCE_API_KEY` |
+| **API Route** | gpt-6.1-sol | ✅ | ✅ | OpenAI-compatible LLM preset. Configure an embedding provider separately. Key: `API_ROUTE_API_KEY`. [Setup guide](../python/guides/provider-configuration.md#api-route) |
| **Atlas Cloud** | `deepseek-ai/deepseek-v4-flash`, `deepseek-ai/deepseek-v4-pro`, `moonshotai/kimi-k3`, `qwen/qwen3.5-plus`, `openai/gpt-5.5`, `anthropic/claude-sonnet-4.6` | ✅ | ✅ | OpenAI-compatible gateway serving DeepSeek, Z.ai, Moonshot, Qwen, MiniMax, OpenAI, Anthropic and Google models under vendor-prefixed ids. LLM only — no embeddings API. `glm-5.x` models reject the forced `tool_choice` structured extraction uses; pick another model. Keys: `ATLASCLOUD_API_KEY` |
| **Alibaba Bailian** | qwen-plus / qwen-turbo / qwen3.6-plus / deepseek-r1 | ✅ | ✅ | Works out of the box |
| **Alibaba Bailian** | qwen-max / deepseek-v3 | ❌ | ❌ | Only `json_object`; not compatible with function-calling structured output |
diff --git a/docs/en/python/guides/provider-configuration.md b/docs/en/python/guides/provider-configuration.md
index cbe1dd1..e5ef8bd 100644
--- a/docs/en/python/guides/provider-configuration.md
+++ b/docs/en/python/guides/provider-configuration.md
@@ -81,6 +81,31 @@ llm, emb = create_client(
# Avoid glm-5.x here: it rejects the forced tool_choice that extraction uses.
```
+### API Route
+
+Set `API_ROUTE_API_KEY` to a key from [API Route](https://www.api-route.com).
+The preset uses `https://global.api-route.com/v1` and defaults to `gpt-6.1-sol`.
+Configure an embedding provider separately:
+
+```python
+from hyperextract import create_client
+
+# Keys: API_ROUTE_API_KEY for the LLM, OPENAI_API_KEY for embeddings.
+llm, emb = create_client(
+ llm="api-route", # override with "api-route:<model-id>"
+ embedder="openai:text-embedding-3-small",
+)
+```
+
+Use a model ID from the [model catalog](https://www.api-route.com/pricing) or
+the authenticated `GET https://global.api-route.com/v1/models` response.
+For CLI configuration:
+
+```bash
+he config llm -p api-route -m gpt-6.1-sol
+he config embedder -p openai -m text-embedding-3-small
+```
+
### Cheaper Inference
```python
diff --git a/docs/zh/concepts/provider-system.md b/docs/zh/concepts/provider-system.md
index 6de2305..d2a6a51 100644
--- a/docs/zh/concepts/provider-system.md
+++ b/docs/zh/concepts/provider-system.md
@@ -11,6 +11,7 @@ Hyper-Extract 支持以下接入方式:**OpenAI**、**Anthropic**、**Google G
| 平台 | 模型 | 函数调用 | 兼容性 | 备注 |
|------|------|:--------:|:------:|------|
| **OpenAI** | gpt-4o / gpt-4o-mini / gpt-5 | ✅ | ✅ | 官方原生支持,推荐 |
+| **API Route** | gpt-6.1-sol | ✅ | ✅ | OpenAI 兼容 LLM 预设,嵌入模型需单独配置。密钥:`API_ROUTE_API_KEY`。[配置指南](../python/guides/provider-configuration.md#api-route) |
| **Anthropic** | claude-opus-4-8 / claude-sonnet-4-6 / claude-haiku-4-5 | ✅(工具调用) | ✅ | 仅 LLM——无嵌入接口(请搭配 OpenAI 兼容嵌入器)。需 `hyperextract[anthropic]` |
| **Google Gemini** | gemini-3.8-flash / gemini-2.5-flash / gemini-2.5-pro | ✅(工具调用) | ✅ | 仅 LLM——本仓库无成熟嵌入路径(请搭配 OpenAI 兼容嵌入器)。需 `hyperextract[google]`。密钥:`GOOGLE_API_KEY` 或 `GEMINI_API_KEY`。别名:`gemini` |
| **DeepSeek** | deepseek-v4-flash / deepseek-v4-pro | ✅ | ✅ | OpenAI 兼容。V4 模型默认开启"thinking"模式,Hyper-Extract 会自动关闭以保证结构化抽取可用。仅 LLM——无嵌入接口。密钥:`DEEPSEEK_API_KEY` |
diff --git a/docs/zh/python/guides/provider-configuration.md b/docs/zh/python/guides/provider-configuration.md
index 692f49e..6644b18 100644
--- a/docs/zh/python/guides/provider-configuration.md
+++ b/docs/zh/python/guides/provider-configuration.md
@@ -8,6 +8,29 @@
以下三个平台运行**相同的提取任务**,仅客户端配置(前 3 行)不同。
+### API Route
+
+从 [API Route](https://www.api-route.com) 获取密钥并设置环境变量 `API_ROUTE_API_KEY`。
+预设端点为 `https://global.api-route.com/v1`,默认模型为 `gpt-6.1-sol`,嵌入模型需单独配置:
+
+```python
+from hyperextract import create_client
+
+# LLM 使用 API_ROUTE_API_KEY,嵌入模型使用 OPENAI_API_KEY。
+llm, emb = create_client(
+ llm="api-route", # 可用 "api-route:<模型 ID>" 指定其他模型
+ embedder="openai:text-embedding-3-small",
+)
+```
+
+可用模型以[模型目录](https://www.api-route.com/pricing)或携带密钥调用
+`GET https://global.api-route.com/v1/models` 的响应为准。CLI 配置示例:
+
+```bash
+he config llm -p api-route -m gpt-6.1-sol
+he config embedder -p openai -m text-embedding-3-small
+```
+
### OpenAI
```python
diff --git a/hyperextract/utils/client.py b/hyperextract/utils/client.py
index 47e089d..e22c4b9 100644
--- a/hyperextract/utils/client.py
+++ b/hyperextract/utils/client.py
@@ -71,6 +71,11 @@ PROVIDER_PRESETS: dict[str, dict[str, str | None]] = {
"default_llm": "gpt-5.4-mini",
"default_embedder": None,
},
+ "api-route": {
+ "base_url": "https://global.api-route.com/v1",
+ "default_llm": "gpt-6.1-sol",
+ "default_embedder": None,
+ },
# Atlas Cloud. OpenAI-compatible aggregator serving DeepSeek, Z.ai, Moonshot,
# Qwen, MiniMax, OpenAI, Anthropic and Google models under vendor-prefixed
# ids such as "deepseek-ai/deepseek-v4-flash". Forced tool_choice (which
@@ -133,6 +138,7 @@ PROVIDER_API_KEY_ENV: dict[str, tuple[str, ...]] = {
"deepseek": ("DEEPSEEK_API_KEY",),
"orcarouter": ("ORCAROUTER_API_KEY",),
"cheaperinference": ("CHEAPER_INFERENCE_API_KEY",),
+ "api-route": ("API_ROUTE_API_KEY",),
"atlascloud": ("ATLASCLOUD_API_KEY",),
}
diff --git a/tests/cli/test_config.py b/tests/cli/test_config.py
index cbc5011..c16f0ed 100644
--- a/tests/cli/test_config.py
+++ b/tests/cli/test_config.py
@@ -35,6 +35,20 @@ def test_save_creates_custom_parent_dir(tmp_path):
assert reloaded.llm.model == "gpt-4o-mini"
+def test_api_route_config_round_trip_uses_provider_endpoint_and_key(tmp_path, monkeypatch):
+ monkeypatch.setenv("API_ROUTE_API_KEY", "route-test")
+ monkeypatch.setenv("OPENAI_API_KEY", "openai-test")
+ monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
+ cfg_path = tmp_path / "config.toml"
+ ConfigManager(cfg_path).set_llm(provider="api-route", model="gpt-6.1-sol")
+
+ config = ConfigManager(cfg_path).get_llm_config()
+ assert config.provider == "api-route"
+ assert config.model == "gpt-6.1-sol"
+ assert config.base_url == "https://global.api-route.com/v1"
+ assert config.api_key == "route-test"
+
+
@_POSIX_ONLY
def test_save_sets_owner_only_permissions(tmp_path):
cfg_path = tmp_path / "config.toml"
diff --git a/tests/utils/test_api_route.py b/tests/utils/test_api_route.py
new file mode 100644
index 0000000..a3d5cd7
--- /dev/null
+++ b/tests/utils/test_api_route.py
@@ -0,0 +1,22 @@
+"""API Route client configuration contracts."""
+
+from hyperextract.utils.client import create_llm
+
+
+def test_create_llm_api_route(monkeypatch):
+ """The named preset selects the API Route endpoint and provider key."""
+ monkeypatch.setenv("OPENAI_API_KEY", "openai-test")
+ monkeypatch.setenv("API_ROUTE_API_KEY", "route-test")
+ llm = create_llm("api-route")
+ assert llm.model_name == "gpt-6.1-sol"
+ assert llm.openai_api_base == "https://global.api-route.com/v1"
+ assert llm.openai_api_key.get_secret_value() == "route-test"
+
+
+def test_create_llm_api_route_overrides(monkeypatch):
+ """Explicit model and key override the preset and environment defaults."""
+ monkeypatch.setenv("API_ROUTE_API_KEY", "route-test")
+ llm = create_llm("api-route:custom-model", api_key="explicit-test")
+ assert llm.model_name == "custom-model"
+ assert llm.openai_api_base == "https://global.api-route.com/v1"
+ assert llm.openai_api_key.get_secret_value() == "explicit-test"