接入文档Getting Started

02端点与协议Endpoints & protocols

自助接入只有一个 base_url:https://console.solunarai.com(注册并充值后在 console 生成 key)。它同时支持下面两种协议。Self-serve has a single base_url: https://console.solunarai.com (generate a key in the console after you register and top up). It supports both protocols below.

企业 / 高并发需要专属直连接入?见 §22 联系 service@solunarai.com 单独开通,不走本页自助流程。Enterprise / high-volume needing a dedicated direct endpoint? See §22 — contact service@solunarai.com, handled outside this self-serve flow.

何时用哪个:要 Claude 全部原生能力(thinking、原生 tool streaming、metadata)→ /v1/messages;工具只说 OpenAI 格式 → /v1/chat/completions;调 GPT → 只走 /v1/chat/completions。Which to use: full Claude native capabilities (thinking, native tool streaming, metadata) → /v1/messages; OpenAI-only tools → /v1/chat/completions; GPT → /v1/chat/completions only.

03鉴权Authentication

注册并充值后,在 console → 令牌 / API Keys 生成 key(sk-…)。两种协议用不同的鉴权头:After you register and top up, generate a key (sk-…) in console → Tokens / API Keys. The two protocols use different auth headers:

• key 即身份 + 计费主体,勿硬编码进前端 / 公开仓库;泄漏即在 console 吊销重发。A key is identity + billing subject — never hardcode it into a frontend or public repo; revoke and reissue in the console if leaked.
• 同一个 console key 两种协议通用,按上面的头分别带即可。One console key works for both protocols — just send the matching header.

04模型目录与能力矩阵Catalog & capability matrix

完整模型清单 + 单价以登录后 console 为准。下表为能力口径。The full model list + pricing lives in the console after login. The tables below are the capability reference.

Claude 全系Claude family (/v1/messages dash · /v1/chat/completions dot)(/v1/messages dash · /v1/chat/completions dot)

• dot/dash 双名:同一模型,/v1/messages 用 dash(claude-sonnet-4-6),/v1/chat/completions 用 dot(claude-sonnet-4.6)。确切名称以 console 模型列表为准。dot/dash dual names: same model — /v1/messages uses dash (claude-sonnet-4-6), /v1/chat/completions uses dot (claude-sonnet-4.6). The exact names are whatever the console model list shows.
• 大输出(>16K)请开 stream:true,否则易触发 HTTP 超时。For large outputs (>16K), set stream:true to avoid HTTP timeouts.

OpenAI / GPTOpenAI / GPT NEW (单名,只走 /v1/chat/completions)(single name, /v1/chat/completions only)

• gpt-5.5 是 reasoning 模型:输出含推理 token;max_tokens 给太小会返回 200 但无可见正文 → 设足够大的输出上限(§06)。gpt-5.5 is a reasoning model: output includes reasoning tokens; too small a max_tokens returns 200 with no visible content → set a generous output cap (§06).
• GPT 的缓存 ≠ Anthropic Prompt Cache:GPT 走 OpenAI 自家自动输入缓存(§06 / §07)。GPT cache ≠ Anthropic Prompt Cache: GPT uses OpenAI's own automatic input cache (§06 / §07).

05Claude 接入Claude integration (/v1/messages 原生)(/v1/messages native)

推荐路径,自动省钱(§07)+ 全原生能力保真。Recommended path — automatic savings (§07) + full native fidelity.

Python (anthropic SDK)(anthropic SDK)

import anthropic
client = anthropic.Anthropic(
    api_key="sk-your-console-key",
    base_url="https://console.solunarai.com",   # SDK appends /v1/messages
)
msg = client.messages.create(
    model="claude-sonnet-4-6",        # dash name
    max_tokens=1024,
    system="You are a helpful assistant.",   # long system caches automatically (§07)
    messages=[{"role": "user", "content": "Introduce prompt cache in one line."}],
)
print(msg.content[0].text)
print(msg.usage)   # check cache_read_input_tokens

curl

curl https://console.solunarai.com/v1/messages \
  -H "x-api-key: sk-your-console-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1024,
       "system":"You are a helpful assistant.",
       "messages":[{"role":"user","content":"Hello"}]}'

thinking(Fable 5 / Opus 4.8 / 4.7 / Sonnet 4.6):"thinking":{"type":"adaptive"} + "output_config":{"effort":"high"}。tool use / vision / streaming 按原生用法,网关全保真透传(§18)。Thinking (Fable 5 / Opus 4.8 / 4.7 / Sonnet 4.6): "thinking":{"type":"adaptive"} + "output_config":{"effort":"high"}. Tool use / vision / streaming behave natively — the gateway passes them through unmodified (§18).

06OpenAI / GPT 接入OpenAI / GPT integration NEW

GPT 系列与所有 OpenAI 兼容客户端走这条路径。The GPT family and every OpenAI-compatible client use this path.

Python (openai SDK)(openai SDK)

from openai import OpenAI
client = OpenAI(
    api_key="sk-your-console-key",
    base_url="https://console.solunarai.com/v1",   # note the /v1
)
r = client.chat.completions.create(
    model="gpt-5.5",
    max_tokens=4096,        # reasoning model: give it room, or you get 200 with empty content
    messages=[{"role": "user", "content": "Introduce yourself in one line."}],
)
print(r.choices[0].message.content)
print(r.usage)   # check prompt_tokens_details.cached_tokens

两件事要分清Two things to keep straight

• reasoning(gpt-5.5):先"思考"再回答,max_tokens 太小 → 预算被推理吃光 → HTTP 200 但 content 为空。设足够大的输出上限(如 ≥4096)。reasoning (gpt-5.5): it thinks before answering — too small a max_tokens means the budget is spent on reasoning → HTTP 200 with empty content. Set a generous cap (e.g. ≥4096).
• OpenAI 缓存 vs Anthropic Prompt Cache:GPT 走 OpenAI 官方自动输入缓存,相同前缀重复请求命中段约 0.1× 输入价,无需任何 cache_control;命中看 usage.prompt_tokens_details.cached_tokens。Claude 走网关注入的 Anthropic Prompt Cache(§07),机制不同,别混。OpenAI cache vs Anthropic Prompt Cache: GPT uses OpenAI's official automatic input cache — repeated identical prefixes bill the cached portion at ≈0.1× input, no cache_control needed; check usage.prompt_tokens_details.cached_tokens. Claude uses the gateway-injected Anthropic Prompt Cache (§07) — different mechanism, don't conflate.
• Claude 也可走此路径(dot 名),同样经网关自动缓存(2026-06-15 实测 cached_tokens=1219)。Claude can also use this path (dot name) and still caches via the gateway (measured cached_tokens=1219, 2026-06-15).

07★ Prompt Cache(0 代码改动)★ Prompt Cache (zero code change)

机制:走 Claude 时,网关自动给 system prompt 注入缓存标记 —— 你不改一行代码。重复的 system / 长上下文在后续请求按缓存价计费(读取约全价 1/10)。How it works: on Claude, the gateway automatically injects cache markers on your system prompt — no code change. A repeated system / long context is billed at the cache rate on later requests (reads ≈ 1/10 of full price).

• 触发:被缓存内容(通常 system)需达上游最小可缓存长度(随模型不同,约 2048–4096 tokens:Sonnet 4.6 / Fable 5 = 2048,Opus 4.8 / 4.7 与 Haiku 4.5 = 4096),且两次间隔在缓存有效期内。低于阈值静默不缓存。Trigger: cached content (usually system) must reach the upstream minimum cacheable length (model-dependent, ≈ 2048–4096 tokens: Sonnet 4.6 / Fable 5 = 2048, Opus 4.8 / 4.7 and Haiku 4.5 = 4096), within the cache window between calls. Below the threshold it silently won't cache.
• 省多少:缓存命中段按全价 1/10 计(接近约 90% 上限);重复 system 实测端到端约 87%。How much: cached hits bill at 1/10 (~90% ceiling); end-to-end about 87% measured on a repeated-system test.
• 看是否命中:/v1/messages 读 usage.cache_read_input_tokens > 0;/v1/chat/completions 读 usage.prompt_tokens_details.cached_tokens > 0。Hit check: /v1/messages → usage.cache_read_input_tokens > 0; /v1/chat/completions → usage.prompt_tokens_details.cached_tokens > 0.
• 长上下文 / RAG:可在 system 块标 {"type":"ephemeral","ttl":"1h"}(写贵约 2×、命中读恒约 0.1×,适合长会话 / 反复问同一份长文档)。Long context / RAG: mark a system block {"type":"ephemeral","ttl":"1h"} (write ≈2×, hits read ≈0.1× — good for long sessions / repeatedly querying one long document).

这是 Anthropic 官方 Prompt Cache,与"我们不缓存你的内容"(§17)不冲突:它是上游侧对你自己请求前缀的计费优化,按工作区隔离,不跨客户。这与"推理层响应缓存已禁用"是两件事。This is the official Anthropic Prompt Cache and does not conflict with "we don't store your content" (§17): it's an upstream billing optimization on your own request prefix, isolated per workspace, never shared across customers. That is separate from "the inference-layer response cache is disabled."

速查表 — 找你的工具Find your tool

先在下表找到你的客户端 / 智能体,看走哪条路径、模型名怎么写,再点"跳转"看配置。Find your client / agent below — see which path and model-name form to use, then jump to its config.

08Anthropic SDK (Python / Node)(Python / Node)

base_url = https://console.solunarai.com · key = x-api-key · model = Claude dash 名。Python 见 §05。base_url = https://console.solunarai.com · key = x-api-key · model = Claude dash name. Python in §05.

Node (@anthropic-ai/sdk)

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
  apiKey: "sk-your-console-key",
  baseURL: "https://console.solunarai.com",
});
const msg = await client.messages.create({
  model: "claude-sonnet-4-6", max_tokens: 1024,
  system: "You are a helpful assistant.",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(msg.content[0].text);

09OpenAI SDK (Python / Node)(Python / Node)

base_url = https://console.solunarai.com/v1 · key = Authorization: Bearer · model = gpt-5.5 等或 Claude dot 名。Python 见 §06。base_url = https://console.solunarai.com/v1 · key = Authorization: Bearer · model = gpt-5.5 etc. or a Claude dot name. Python in §06.

Node (openai)

import OpenAI from "openai";
const client = new OpenAI({
  apiKey: "sk-your-console-key",
  baseURL: "https://console.solunarai.com/v1",
});
const r = await client.chat.completions.create({
  model: "gpt-5.5", max_tokens: 4096,
  messages: [{ role: "user", content: "Hello" }],
});
console.log(r.choices[0].message.content);

10Claude Code

走 Anthropic 原生 /v1/messages(自动省钱)。设环境变量指向网关:Uses Anthropic-native /v1/messages (automatic savings). Point the env vars at the gateway:

export ANTHROPIC_BASE_URL="https://console.solunarai.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-console-key"   # or ANTHROPIC_API_KEY
export ANTHROPIC_MODEL="claude-sonnet-4-6"          # dash name
claude

启动后照常用;Prompt Cache 自动生效,无需改任何配置。换模型直接改 ANTHROPIC_MODEL(用 console 清单里的确切 dash 名)。Use it as usual; Prompt Cache works automatically, no config change. To switch models, change ANTHROPIC_MODEL (use the exact dash name from the console list).

11Cursor

走 OpenAI 兼容路径。Settings → Models:Uses the OpenAI-compatible path. Settings → Models:

• Override OpenAI Base URL = https://console.solunarai.com/v1
• OpenAI API Key = sk-your-console-key
• Add model(自定义模型名):gpt-5.5 或 Claude dot 名 claude-sonnet-4.6Add model (custom name): gpt-5.5 or a Claude dot name claude-sonnet-4.6

保存后在模型选择器里选刚加的模型即可。Save, then pick the model you added in the model selector.

12Cline / Roo Code (VS Code 扩展)(VS Code extension)

用 OpenAI Compatible 提供方:Use the OpenAI Compatible provider:

• Base URL = https://console.solunarai.com/v1
• API Key = sk-your-console-key
• Model ID = gpt-5.5 或 Claude dot 名 claude-sonnet-4.6or Claude dot name claude-sonnet-4.6

也可用 Anthropic 提供方走 native:Base URL = https://console.solunarai.com、Key = sk-…、模型用 dash 名。Or use the Anthropic provider for native: Base URL = https://console.solunarai.com, Key = sk-…, model = dash name.

Roo Code(Cline 的活跃分支)配置完全相同:用 OpenAI Compatible 或 Anthropic 提供方,按上面填即可。Roo Code (an active Cline fork) is configured identically — use the OpenAI Compatible or Anthropic provider with the same values above.

13LangChain / LangGraph

走 Claude(native,自动省钱)Claude (native, auto savings)

from langchain_anthropic import ChatAnthropic
llm = ChatAnthropic(
    model="claude-sonnet-4-6",
    api_key="sk-your-console-key",
    base_url="https://console.solunarai.com",
)
print(llm.invoke("Hello").content)

走 GPT 或 OpenAI 兼容GPT / OpenAI-compatible

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
    model="gpt-5.5",
    api_key="sk-your-console-key",
    base_url="https://console.solunarai.com/v1",
    max_tokens=4096,
)
print(llm.invoke("Hello").content)

LangGraph 节点里直接复用上面的 llm 实例。Reuse the llm instance directly inside LangGraph nodes.

14更多 AI Agent 与客户端More AI agents & clients

更多主流 AI agent / 客户端的具体填法;凡"OpenAI 兼容"的,都按上面速查表的统一规则(base_url 带 /v1 + Bearer key + 模型名)。Concrete config for more mainstream AI agents / clients. Anything "OpenAI-compatible" follows the uniform rules in the lookup table above (base_url with /v1 + Bearer key + model name).

Continue (VS Code / JetBrains)(VS Code / JetBrains)

在 config.json(或 config.yaml)的 models 里加条目,native 与兼容两种都可:Add entries under models in config.json (or config.yaml) — both native and compatible work:

{
  "models": [
    { "title": "Solunar Claude", "provider": "anthropic",
      "apiBase": "https://console.solunarai.com",
      "apiKey": "sk-your-console-key", "model": "claude-sonnet-4-6" },
    { "title": "Solunar GPT", "provider": "openai",
      "apiBase": "https://console.solunarai.com/v1",
      "apiKey": "sk-your-console-key", "model": "gpt-5.5" }
  ]
}

Aider (CLI 编码 agent)(CLI coding agent)

走 OpenAI 兼容(底层用 litellm,模型名加 openai/ 前缀):Use the OpenAI-compatible route (litellm under the hood — prefix the model with openai/):

export OPENAI_API_BASE="https://console.solunarai.com/v1"
export OPENAI_API_KEY="sk-your-console-key"
aider --model openai/gpt-5.5
# or Claude (dot name):
aider --model openai/claude-sonnet-4.6

桌面 & 自托管客户端Desktop & self-hosted clients

都走 OpenAI 兼容,在各自"自定义 / OpenAI 接口"设置里填:All OpenAI-compatible — fill these into each app's "custom / OpenAI endpoint" settings:

Dify (Agent / 工作流平台)(agent / workflow platform)

• 设置 → 模型供应商 → OpenAI-API-compatible:API endpoint URL https://console.solunarai.com/v1 + API Key sk-… + Model Name gpt-5.5 / claude-sonnet-4.6。Settings → Model Provider → OpenAI-API-compatible: API endpoint URL https://console.solunarai.com/v1 + API Key sk-… + Model Name gpt-5.5 / claude-sonnet-4.6.
• 然后在应用 / Agent 编排里选该模型即可。Then select that model in your app / agent orchestration.

其它任何"OpenAI 兼容"客户端(n8n、Flowise、各类桌面 App…)同理:能填 Base URL + Key + 模型名就能接。Any other "OpenAI-compatible" client (n8n, Flowise, various desktop apps…) works the same way: if it lets you set Base URL + Key + model name, it connects.

15计费与额度Billing & credits

• 预付额度:充值后按用量扣减,console 看余额 / 明细。Prepaid credits: usage is deducted from your balance; see balance/usage in the console.
• 充值:在线信用卡(Stripe)+ 兑换码(国内卡 / 对公 / SWIFT)。Top up: card online (Stripe) + redemption codes (domestic cards / wire / SWIFT).
• 价格 / 倍率:登录后 console 可见。Pricing / rates: visible in the console after login.
• 缓存计费:命中按缓存价(约 0.1×),不按全价(§07)。Cache billing: hits bill at the cache rate (≈0.1×), not full price (§07).
• 退款:见退款政策(已消费不退;未消费 14 天内可申请;人工审核)。Refunds: see the Refund Policy (consumed credit is non-refundable; unused within 14 days may be requested; manual review).

16限额与速率Limits & rate

• 账号有并发 / 速率限制以保障稳定;起步阶段单笔 / 单日充值有上限(风控)。Accounts have concurrency / rate limits for stability; during onboarding, per-transaction / per-day top-up caps apply (risk control).
• 余额为 0 或撞限额会返回相应错误(§19)。Zero balance or hitting a limit returns the corresponding error (§19).
• 需要更高额度 / 并发或企业实施 → service@solunarai.com。For higher limits / concurrency or enterprise rollout → service@solunarai.com.

17数据边界(你的数据只属于你)Data boundary (your data is yours)

• 不截取、不转卖、不训练:不拿你的 prompt / 输出训练模型,不转卖。No harvesting, no resale, no training: we don't train on your prompts/outputs, and we don't resell them.
• 不存正文:控制面与推理层均只记用量元数据(模型名、token 数、时间、IP、request_id),不持久存储正文。No content storage: both the control plane and the inference layer record only usage metadata (model, token counts, time, IP, request_id), never your content.
• 不跨客户缓存:已禁用推理层响应缓存,不跨请求 / 客户复用内容(这与 §07 的 Prompt Cache 是两回事)。No cross-customer cache: the inference-layer response cache is disabled; content is never reused across requests/customers (separate from the Prompt Cache in §07).
• 上游:请求经推理层转发给官方 Anthropic / OpenAI 履行;按其商用条款,你的内容不用于训练其模型;数据可能发往美国上游(与隐私政策一致)。Upstream: requests are forwarded to the official Anthropic / OpenAI for fulfillment; under their commercial terms your content is not used to train their models; data may go to US upstreams (consistent with the Privacy Policy).
• GLM 档(性价比/国产,可选)例外:GLM 模型的请求经智谱/Z.ai 的授权折扣转售渠道路由(非官方直连),可能受中华人民共和国法域管辖;留存/训练无合同性保证。仅在你显式选 GLM 模型时使用;敏感内容请勿用此档。详见隐私政策 §3/§4。GLM tier (value / Chinese-model, optional) exception: GLM requests are routed via an authorized discount reseller of Zhipu/Z.ai (not the official API) and may be subject to PRC jurisdiction; no contractual guarantee on retention/training. Used only when you explicitly select a GLM model; don't send sensitive content to this tier. See Privacy Policy §3/§4.

详见隐私政策 / 服务条款 / 可接受使用政策。See the Privacy Policy / Terms / Acceptable Use Policy.

18验证"官方纯正 / 不降智"Verify integrity (no downgrade)

我们承诺官方通道、不降级,你可自验:We promise official routing, no downgrade. You can verify:

• 行为一致:同 prompt 与官方示例行为一致(无裁剪 / 降参)。Consistent behavior: same prompt behaves like the official example (no truncation / param downgrade).
• 完整能力:走 /v1/messages 时,Claude 的 tool use、thinking、tool_choice、metadata、streaming 全保真透传(网关唯一改动 = 注入 cache 标记,不改变语义)。Full capabilities: on /v1/messages, Claude's tool use, thinking, tool_choice, metadata, and streaming are passed through with full fidelity (the gateway's only change is the cache marker, which is non-semantic).
• 原生元数据:usage / stop_reason 等为上游原生返回。GPT 走官方 OpenAI API,原生返回。Native metadata: usage / stop_reason are returned natively by the upstream. GPT runs on the official OpenAI API, native responses.
• 我们不做:静默换小模型、截断上下文、改写你 prompt 的内容或语义。We never: silently swap to a smaller model, truncate context, or alter the content or meaning of your prompt.

19错误码参考Error codes

返回沿用上游 HTTP 语义(Anthropic / OpenAI 风格)。SDK 一律用类型化异常判别,别用错误信息字符串匹配。Responses follow upstream HTTP semantics (Anthropic / OpenAI style). Always branch on the SDK's typed exceptions, not on error-message string matching.

cache_read=0(没省到钱)不是错误,排查见 §20。cache_read=0 (no savings) is not an error — see §20.

20故障排查Troubleshooting

21FAQ

接入要改代码吗? 只改 base_url + api_key 两行;Claude 的 Prompt Cache 自动,0 额外改动(迁移见下)。Any code change? Just base_url + api_key; Claude's Prompt Cache is automatic, zero extra change (see Migration).

省钱是真的吗? Claude 走网关自动注入官方 Prompt Cache,重复 system 场景生产实测端到端约 87%、接近约 90% 缓存上限(2026-06-15)。Is the saving real? On Claude the gateway auto-injects the official Prompt Cache — about 87% end-to-end measured on repeated-system workloads, approaching the ~90% cache ceiling (2026-06-15).

支持 GPT 吗? 支持 gpt-5.5 / gpt-5.4 / gpt-5.4-mini,走 /v1/chat/completions(§06)。GPT supported? Yes — gpt-5.5 / gpt-5.4 / gpt-5.4-mini, via /v1/chat/completions (§06).

你们会看 / 存我的 prompt 吗? 不存正文、不缓存内容、不训练、不转卖(§17)。Do you read / store my prompts? No content stored, no content caching, no training, no resale (§17).

是"降智"中转吗? 不是。官方通道、原生返回、可自验(§18)。Is this a "downgraded" relay? No. Official routing, native responses, self-verifiable (§18).

Claude 和 GPT 的缓存一样吗? 不一样:Claude = 网关注入的 Anthropic Prompt Cache;GPT = OpenAI 自家自动输入缓存(§06/§07)。Same cache for Claude and GPT? No: Claude = gateway-injected Anthropic Prompt Cache; GPT = OpenAI's own automatic input cache (§06/§07).

国内卡能付吗? 信用卡走 Stripe;不便的用兑换码 / 对公(§15)。Can I pay with a domestic card? Cards via Stripe; otherwise redemption codes / wire (§15).

22联系 / 企业实施Contact / enterprise

技术接入 · 提额 · 企业实施 / 专属直连(高校 / SMB 定制化):Integration · higher limits · enterprise & dedicated direct access (university / SMB): service@solunarai.com

→迁移指南Migration guide

从 Anthropic 官方直连(改 2 行)From Anthropic direct (2 lines)

  client = anthropic.Anthropic(
-     api_key="official-key",
+     api_key="sk-your-console-key",
+     base_url="https://console.solunarai.com",
  )

模型名不变(dash);Prompt Cache 自动生效。Model names unchanged (dash); Prompt Cache kicks in automatically.

从 OpenAI 官方(改 base_url + key)From OpenAI direct (base_url + key)

  client = OpenAI(
-     api_key="official-key",
+     api_key="sk-your-console-key",
+     base_url="https://console.solunarai.com/v1",
  )

gpt-5.5 等名称直接用;Claude 模型用 dot 名。Use gpt-5.5 etc. directly; for Claude models use the dot name.