feat(gateway): add API Route hybrid gateway

.env.example

@@ -216,6 +216,11 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # OPENAI_BASE_URL=https://api.aimlapi.com/v1
 # OPENAI_MODEL=gpt-4o
 
+# For API Route, the dedicated key enables the OpenAI-compatible route:
+# API_ROUTE_API_KEY=your-api-route-key-here
+# OPENAI_BASE_URL=https://global.api-route.com/v1
+# OPENAI_MODEL=claude-sonnet-4-6
+
 # For LLMTR, prefer its dedicated key. Raw env setup must also set
 # OPENAI_BASE_URL and OPENAI_MODEL. OPENAI_API_KEY remains supported:
 # LLMTR_API_KEY=your-llmtr-key-here

README.md

@@ -313,6 +313,7 @@ Advanced and source-build guides:
 | LLMTR | `/provider` or OpenAI-compatible env vars | Multi-model gateway at `https://llmtr.com/v1`; `/provider` and `--provider llmtr` default to `deepseek/deepseek-v4-flash`, while raw env setup must set `OPENAI_BASE_URL=https://llmtr.com/v1` and `OPENAI_MODEL`; accepts `LLMTR_API_KEY` or `OPENAI_API_KEY` after the route is selected and discovers tool-capable Chat Completions models from the public catalog |
 | Command Code | `/provider` or OpenAI-compatible env vars | Hybrid OpenAI-compatible gateway at `https://api.commandcode.ai/provider/v1`; `/provider` and `--provider commandcode` default to `deepseek/deepseek-v4-flash`, while raw env setup must set `OPENAI_BASE_URL=https://api.commandcode.ai/provider/v1` and `OPENAI_MODEL`; requires `CMD_API_KEY`, `COMMANDCODE_API_KEY`, or the official `COMMAND_CODE_API_KEY` after the route is selected and discovers Chat Completions models from the public catalog. Claude models are unsupported by this Chat Completions integration |
 | ApiSmart | `/provider` or `APISMART_API_KEY` | Uses `https://gw.apismart.ai/v1`, defaults to `DEEPSEEK_V4_FLASH`, and supports optional `APISMART_MODEL` plus authenticated model discovery |
+| API Route | `/provider` or `API_ROUTE_API_KEY` | Uses `https://global.api-route.com/v1`, defaults to `claude-sonnet-4-6`, and supports optional `API_ROUTE_MODEL` plus authenticated model discovery |
 | Hicap | `/provider` or OpenAI-compatible env vars | Uses `api-key` auth, discovers models from unauthenticated `/models`, and supports Responses mode for `gpt-` models |
 | Fireworks AI | `/provider` or env vars | First-class provider with 276 curated models (DeepSeek, Qwen, Llama, Gemma, and more); uses `FIREWORKS_API_KEY` |
 | LongCat | `/provider` or env vars | Meituan LongCat OpenAI-compatible API at `https://api.longcat.chat/openai/v1`; uses `LONGCAT_API_KEY` and defaults to `LongCat-2.0` |

src/integrations/compatibility.test.ts

@@ -58,6 +58,7 @@ const EXPECTED_PRESETS = [
   'opencode',
   'opencode-go',
   'clinepass',
+  'api-route',
 ] as const satisfies readonly ProviderPreset[]
 
 describe('compatibility mappings', () => {

src/integrations/gateways/api-route.test.ts

@@ -0,0 +1,174 @@
+import { expect, test } from 'bun:test'
+
+import { routeForPreset } from '../compatibility.js'
+import { getProviderPresetUiMetadata } from '../providerUiMetadata.js'
+import {
+  resolveActiveRouteIdFromEnv,
+  resolveRouteCredentialValue,
+  resolveRouteIdFromBaseUrl,
+} from '../routeMetadata.js'
+import gateway, { mapApiRouteModel } from './api-route.js'
+
+test('API Route uses a dedicated hybrid OpenAI-compatible gateway contract', () => {
+  expect(gateway.defaultBaseUrl).toBe('https://global.api-route.com/v1')
+  expect(gateway.defaultModel).toBe('claude-sonnet-4-6')
+  expect(gateway.setup.credentialEnvVars).toEqual(['API_ROUTE_API_KEY'])
+  expect(gateway.setup.dedicatedCredentialsOnly).toBe(false)
+  expect(gateway.preset?.apiKeyEnvVars).toEqual(['API_ROUTE_API_KEY'])
+  expect(gateway.validation).toMatchObject({
+    kind: 'credential-env',
+    routing: { matchDefaultBaseUrl: true },
+    credentialEnvVars: ['API_ROUTE_API_KEY', 'OPENAI_API_KEYS', 'OPENAI_API_KEY'],
+  })
+  expect(gateway.transportConfig).toEqual({
+    kind: 'openai-compatible',
+    openaiShim: {
+      supportsApiFormatSelection: false,
+      supportsAuthHeaders: false,
+      maxTokensField: 'max_tokens',
+    },
+  })
+  expect(gateway.catalog?.source).toBe('hybrid')
+  expect(gateway.catalog?.discovery?.requiresAuth).toBe(true)
+  expect(gateway.catalog?.models?.map(model => model.apiName)).toEqual([
+    'claude-sonnet-4-6',
+  ])
+})
+
+test('API Route preset uses the existing generic profile path', () => {
+  expect(routeForPreset('api-route')).toEqual({
+    vendorId: 'openai',
+    gatewayId: 'api-route',
+    routeId: 'api-route',
+  })
+  expect(
+    getProviderPresetUiMetadata('api-route', {
+      API_ROUTE_API_KEY: 'test-api-route-key',
+    }),
+  ).toMatchObject({
+    apiKey: 'test-api-route-key',
+    baseUrl: 'https://global.api-route.com/v1',
+    model: 'claude-sonnet-4-6',
+    provider: 'api-route',
+    routeId: 'api-route',
+  })
+  expect(
+    getProviderPresetUiMetadata('api-route', {
+      API_ROUTE_API_KEY: 'test-api-route-key',
+      API_ROUTE_MODEL: 'custom-api-route-model',
+      OPENAI_MODEL: 'custom-openai-model',
+    }),
+  ).toMatchObject({
+    model: 'custom-api-route-model',
+  })
+  expect(
+    getProviderPresetUiMetadata('api-route', {
+      API_ROUTE_API_KEY: 'test-api-route-key',
+      OPENAI_MODEL: 'custom-openai-model',
+    }),
+  ).toMatchObject({
+    model: 'custom-openai-model',
+  })
+})
+
+test('API Route profile credentials use the generic fallback only on the canonical inference URL', () => {
+  expect(
+    resolveRouteCredentialValue({
+      routeId: 'api-route',
+      baseUrl: 'https://global.api-route.com/v1',
+      processEnv: { OPENAI_API_KEY: 'saved-profile-key' },
+    }),
+  ).toBe('saved-profile-key')
+
+  expect(
+    resolveRouteCredentialValue({
+      routeId: 'api-route',
+      baseUrl: 'https://proxy.example.com/v1',
+      processEnv: { OPENAI_API_KEY: 'saved-profile-key' },
+    }),
+  ).toBeUndefined()
+
+  const env = { API_ROUTE_API_KEY: 'secret-key' }
+
+  expect(
+    resolveRouteCredentialValue({
+      routeId: 'api-route',
+      baseUrl: 'https://global.api-route.com/v1',
+      processEnv: env,
+    }),
+  ).toBe('secret-key')
+
+  expect(
+    resolveRouteCredentialValue({
+      routeId: 'api-route',
+      baseUrl: 'http://global.api-route.com/v1',
+      processEnv: env,
+    }),
+  ).toBeUndefined()
+
+  expect(
+    resolveRouteCredentialValue({
+      routeId: 'api-route',
+      baseUrl: 'https://global.api-route.com/v1?tenant=proxy',
+      processEnv: env,
+    }),
+  ).toBeUndefined()
+
+  expect(
+    resolveRouteCredentialValue({
+      routeId: 'api-route',
+      baseUrl: 'https://proxy.example.com/v1',
+      processEnv: env,
+    }),
+  ).toBeUndefined()
+})
+
+test('API Route discovery maps chat models and drops non-chat IDs', () => {
+  expect(
+    mapApiRouteModel({
+      id: 'claude-sonnet-4-6',
+      name: 'Claude Sonnet 4.6',
+      context_length: 200000,
+    }),
+  ).toEqual({
+    id: 'claude-sonnet-4-6',
+    apiName: 'claude-sonnet-4-6',
+    label: 'Claude Sonnet 4.6',
+    contextWindow: 200000,
+  })
+
+  expect(
+    mapApiRouteModel({
+      id: 'gpt-4o-mini',
+      owned_by: 'openai',
+    }),
+  ).toEqual({
+    id: 'gpt-4o-mini',
+    apiName: 'gpt-4o-mini',
+    label: 'gpt-4o-mini (openai)',
+  })
+
+  expect(mapApiRouteModel({ id: 'text-embedding-3-small' })).toBeNull()
+  expect(mapApiRouteModel({ id: 'whisper-1' })).toBeNull()
+  expect(mapApiRouteModel({ id: 'dall-e-3' })).toBeNull()
+  expect(mapApiRouteModel({ id: 'gpt-image-1' })).toBeNull()
+  expect(mapApiRouteModel({ id: 'sora-turbo' })).toBeNull()
+  expect(mapApiRouteModel({ id: 'veo-2' })).toBeNull()
+  expect(mapApiRouteModel(null)).toBeNull()
+  expect(mapApiRouteModel({})).toBeNull()
+})
+
+test('API Route route resolution detects endpoints and environment intent', () => {
+  expect(resolveRouteIdFromBaseUrl('https://global.api-route.com/v1')).toBe(
+    'api-route',
+  )
+  expect(
+    resolveRouteIdFromBaseUrl('https://global.api-route.com/v1/chat/completions'),
+  ).toBe('api-route')
+
+  expect(
+    resolveActiveRouteIdFromEnv({
+      API_ROUTE_API_KEY: 'test-key',
+    }),
+  ).toBe('api-route')
+})

src/integrations/gateways/api-route.ts

@@ -0,0 +1,125 @@
+import { defineCatalog, defineGateway } from '../define.js'
+
+const NON_CHAT_MODEL_PATTERN =
+  /(embedding|embed|dall-e|whisper|tts|rerank|moderation|omni-moderation|audio|^gpt-image-|^sora-|^veo-)/i
+
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function getTrimmedString(
+  record: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = record[key]
+  return typeof value === 'string' ? value.trim() : undefined
+}
+
+function getPositiveInteger(value: unknown): number | undefined {
+  if (
+    typeof value === 'number' &&
+    Number.isFinite(value) &&
+    Number.isInteger(value) &&
+    value > 0
+  ) {
+    return value
+  }
+  return undefined
+}
+
+export function mapApiRouteModel(raw: unknown) {
+  if (!isRecord(raw)) {
+    return null
+  }
+
+  const id = getTrimmedString(raw, 'id')
+  if (!id || NON_CHAT_MODEL_PATTERN.test(id)) {
+    return null
+  }
+
+  const name = getTrimmedString(raw, 'name')
+  const ownedBy =
+    getTrimmedString(raw, 'owned_by') || getTrimmedString(raw, 'ownedBy')
+  const label = name || (ownedBy ? `${id} (${ownedBy})` : id)
+  const contextWindow =
+    getPositiveInteger(raw.context_length) ??
+    getPositiveInteger(raw.context_window)
+
+  return {
+    id,
+    apiName: id,
+    label,
+    ...(contextWindow !== undefined ? { contextWindow } : {}),
+  }
+}
+
+const curatedModels = [
+  {
+    id: 'claude-sonnet-4-6',
+    apiName: 'claude-sonnet-4-6',
+    aliases: ['sonnet-4.6', 'claude-sonnet'],
+    modelDescriptorId: 'claude-sonnet-4-6',
+    label: 'Claude Sonnet 4.6',
+    contextWindow: 200_000,
+    maxOutputTokens: 8_192,
+  },
+]
+
+const catalog = defineCatalog({
+  source: 'hybrid',
+  discovery: {
+    kind: 'openai-compatible',
+    requiresAuth: true,
+    mapModel: mapApiRouteModel,
+  },
+  discoveryCacheTtl: '1d',
+  discoveryRefreshMode: 'background-if-stale',
+  allowManualRefresh: true,
+  models: [...curatedModels],
+})
+
+export default defineGateway({
+  id: 'api-route',
+  label: 'API Route',
+  category: 'aggregating',
+  defaultBaseUrl: 'https://global.api-route.com/v1',
+  defaultModel: 'claude-sonnet-4-6',
+  supportsModelRouting: true,
+  setup: {
+    requiresAuth: true,
+    authMode: 'api-key',
+    credentialEnvVars: ['API_ROUTE_API_KEY'],
+    dedicatedCredentialsOnly: false,
+  },
+  startup: {
+    probeReadiness: 'openai-compatible-models',
+  },
+  transportConfig: {
+    kind: 'openai-compatible',
+    openaiShim: {
+      supportsApiFormatSelection: false,
+      supportsAuthHeaders: false,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  preset: {
+    id: 'api-route',
+    description: 'API Route OpenAI-compatible multi-model gateway',
+    vendorId: 'openai',
+    apiKeyEnvVars: ['API_ROUTE_API_KEY'],
+    modelEnvVars: ['API_ROUTE_MODEL', 'OPENAI_MODEL'],
+  },
+  validation: {
+    kind: 'credential-env',
+    routing: {
+      matchDefaultBaseUrl: true,
+      matchBaseUrlHosts: ['global.api-route.com'],
+    },
+    credentialEnvVars: ['API_ROUTE_API_KEY', 'OPENAI_API_KEYS', 'OPENAI_API_KEY'],
+    missingCredentialMessage:
+      'API Route auth is required. Set API_ROUTE_API_KEY.',
+  },
+  catalog,
+  usage: { supported: false },
+})

src/integrations/generated/integrationArtifacts.generated.ts

@@ -20,6 +20,7 @@ import vendorXai from '../vendors/xai.js'
 import vendorXiaomiMimo from '../vendors/xiaomi-mimo.js'
 import vendorZai from '../vendors/zai.js'
 import gatewayAimlapi from '../gateways/aimlapi.js'
+import gatewayApiRoute from '../gateways/api-route.js'
 import gatewayApismart from '../gateways/apismart.js'
 import gatewayAtlasCloud from '../gateways/atlas-cloud.js'
 import gatewayAtomicChat from '../gateways/atomic-chat.js'
@@ -93,7 +94,7 @@ import modelXai from '../models/xai.js'
 import modelXiaomiMimo from '../models/xiaomi-mimo.js'
 
 export const VENDOR_DESCRIPTORS = [vendorAnthropic, vendorBankr, vendorDeepseek, vendorFireworks, vendorGemini, vendorLongcat, vendorMinimax, vendorMoonshot, vendorNearai, vendorOpenai, vendorVenice, vendorXai, vendorXiaomiMimo, vendorZai] as const satisfies readonly VendorDescriptor[]
-export const GATEWAY_DESCRIPTORS = [gatewayAimlapi, gatewayApismart, gatewayAtlasCloud, gatewayAtomicChat, gatewayAzureOpenai, gatewayBedrock, gatewayClinepass, gatewayCloudflare, gatewayCommandcode, gatewayConcentrate, gatewayCustom, gatewayDashscopeCn, gatewayDashscopeIntl, gatewayGithubEnterprise, gatewayGithub, gatewayGitlawbOpengateway, gatewayGroq, gatewayHicap, gatewayKimiCode, gatewayLlmtr, gatewayLmstudio, gatewayMistral, gatewayNvidiaNim, gatewayOllama, gatewayOpencodeGo, gatewayOpencode, gatewayOpenrouter, gatewayTogether, gatewayVertex, gatewayXiaomiMimoToken] as const satisfies readonly GatewayDescriptor[]
+export const GATEWAY_DESCRIPTORS = [gatewayAimlapi, gatewayApiRoute, gatewayApismart, gatewayAtlasCloud, gatewayAtomicChat, gatewayAzureOpenai, gatewayBedrock, gatewayClinepass, gatewayCloudflare, gatewayCommandcode, gatewayConcentrate, gatewayCustom, gatewayDashscopeCn, gatewayDashscopeIntl, gatewayGithubEnterprise, gatewayGithub, gatewayGitlawbOpengateway, gatewayGroq, gatewayHicap, gatewayKimiCode, gatewayLlmtr, gatewayLmstudio, gatewayMistral, gatewayNvidiaNim, gatewayOllama, gatewayOpencodeGo, gatewayOpencode, gatewayOpenrouter, gatewayTogether, gatewayVertex, gatewayXiaomiMimoToken] as const satisfies readonly GatewayDescriptor[]
 export const ANTHROPIC_PROXY_DESCRIPTORS = [anthropicproxyCustom] as const satisfies readonly AnthropicProxyDescriptor[]
 export const BRAND_DESCRIPTORS = [brandClaude, brandDeepseek, brandFireworks, brandGemini, brandGlm, brandGpt, brandKimi, brandLing, brandLlama, brandLongcat, brandMacaron, brandMinimax, brandMistral, brandNearai, brandNemotron, brandOpenaiCompatibleAlias, brandQwen, brandTencent, brandXai, brandXiaomiMimo] as const satisfies readonly BrandDescriptor[]
 export const MODEL_DESCRIPTOR_GROUPS = [modelClaude, modelDeepseek, modelFireworksMerged, modelGemini, modelGlm, modelGpt, modelKimi, modelLing, modelLlama, modelLongcat, modelMacaron, modelMinimax, modelMistral, modelNearai, modelNemotron, modelOpenaiCompatibleAlias, modelOpencode, modelQwen, modelTencent, modelXai, modelXiaomiMimo] as const satisfies readonly (readonly ModelDescriptor[])[]

src/integrations/generated/integrationManifest.generated.ts

@@ -90,6 +90,21 @@ export const PROVIDER_PRESET_MANIFEST = [
       "DASHSCOPE_API_KEY"
     ]
   },
+  {
+    "preset": "api-route",
+    "routeKind": "gateway",
+    "routeId": "api-route",
+    "vendorId": "openai",
+    "gatewayId": "api-route",
+    "description": "API Route OpenAI-compatible multi-model gateway",
+    "apiKeyEnvVars": [
+      "API_ROUTE_API_KEY"
+    ],
+    "modelEnvVars": [
+      "API_ROUTE_MODEL",
+      "OPENAI_MODEL"
+    ]
+  },
   {
     "preset": "apismart",
     "routeKind": "gateway",
@@ -591,6 +606,7 @@ export const ORDERED_PROVIDER_PRESETS = [
   "anthropic",
   "dashscope-cn",
   "dashscope-intl",
+  "api-route",
   "apismart",
   "atlas-cloud",
   "azure-openai",

src/integrations/providerUiMetadata.ts

@@ -47,7 +47,8 @@ function hasUsableEnvValue(envVar: string, value: string | undefined): boolean {
     envVar === 'LLMTR_API_KEY' ||
     envVar === 'CMD_API_KEY' ||
     envVar === 'COMMANDCODE_API_KEY' ||
-    envVar === 'COMMAND_CODE_API_KEY'
+    envVar === 'COMMAND_CODE_API_KEY' ||
+    envVar === 'API_ROUTE_API_KEY'
   ) {
     return hasUsableOpenAICredential(value)
   }