文档目录

首次调用

使用 OpenAI SDK 的 Chat Completions 接口接入。baseURL 填 https://idea.sh.cn/v1，模型名填 idea。

BASE URLhttps://idea.sh.cn/v1

拿到密钥

在控制台的 API keys 新建一个密钥，复制 idea_sk_ 开头的字符串。密钥只在创建时完整显示一次，之后只能看到前缀，请当场保存。

发第一个请求

curl https://idea.sh.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "idea",
    "messages": [{"role": "user", "content": "你好"}]
  }'

下方示例中的 OPENAI_API_KEY 环境变量需要先设为你的完整密钥。也可以使用 Python 或 Node.js SDK：

from openai import OpenAI

client = OpenAI(
    api_key="idea_sk_your_key",
    base_url="https://idea.sh.cn/v1",
)

resp = client.chat.completions.create(
    model="idea",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

两个模型名

用密钥调用时，模型名决定走哪条链路，这两条的行为差别很大：

模型名	行为
`idea`	裸模型，与 OpenAI API 一致：只用你自己传的 system 和 tools。没有人设、记忆、账户技能、项目指令，也不会联网检索或生成文件
`idea-agent`	完整的 iDEA 智能体，与网页端、App 同一条链路：带人设与账户技能，可使用内置检索、网页查询、文档生成

默认用 idea。如果你期待的是网页端那种「会自己查资料、会出文件」的效果，要显式填 idea-agent，否则只会拿到模型的直接回答。本文档中「功能与扩展」整页、以及所有 X-Idea- 开头的扩展请求头，都只在 idea-agent 下生效。

curl https://idea.sh.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "idea-agent",
    "messages": [{"role": "user", "content": "帮我查一下杭州明天的天气"}]
  }'

流式返回

请求体里加 "stream": true，响应使用 SSE。正文从 choices[0].delta.content 读取，以 data: [DONE] 结束。

curl -N https://idea.sh.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "idea",
    "messages": [{"role": "user", "content": "写一首七绝"}],
    "stream": true
  }'

服务还可能发送进度或错误事件。自定义解析器应区分 event: 与正文分片；SDK 使用方先判断分片是否包含 choices。逐字输出的设置见「功能与扩展」。

连不通怎么查

按下面两条命令跑一遍，就能把问题定位到具体某一层。先跑第一条：它不需要密钥，只验证网络和域名。

# 1. 先不带密钥，确认网络和域名通不通（应返回 200 和模型列表）
curl -i -m 15 https://idea.sh.cn/v1/models

# 2. 再带上密钥发一次真实请求，看状态码和 detail
curl -i -m 60 https://idea.sh.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "idea",
    "messages": [{"role": "user", "content": "你好"}]
  }'

然后按拿到的结果对号入座：

现象	原因与处理
第 1 条就超时或报 DNS、证书错误	问题在你本地，服务端没收到请求。多半是代理或防火墙：临时关掉系统代理再试，或确认代理放行 `idea.sh.cn:443`。很多客户端只认 `HTTPS_PROXY` 环境变量，与浏览器能否打开本站无关
第 1 条通，第 2 条返回 401	密钥问题。按响应里的 detail 区分，见「错误码」一页的 401 行
返回 404	地址拼错了。baseURL 已经以 `/v1` 结尾，SDK 会自动补 `/chat/completions`；若客户端要求填「完整地址」，别再手动多写一层 `/v1`
返回 200，但 `content` 是空字符串或 null	多半是 `max_tokens` 给小了。模型默认开启思考，预算会先被思考占用，`finish_reason` 会是 `length`。把 `max_tokens` 提到 512 以上，或不传该字段

控制台的 API keys 页有一列「最近使用」。如果你已经调用过，那里却仍显示「尚未使用」，说明请求根本没到服务器，应该照上表第一行排查本地网络和代理，而不是反复新建密钥。