第一次成功调用 String AI API，归根结底靠三个值：base URL、一个 API key，以及一个模型 ID。其余都是细节。这份五步快速入门带你走完一套 OpenAI 兼容配置，从一个空白终端开始，直到一个能工作的 chat completions 请求；最后列出导致大多数首次调用失败的三个错误，外加一张你很可能遇到的错误码速查表。
如果你更想先用浏览器而不是终端，平台自己的五分钟指南覆盖了 WebChat 入口，桌面启动器在下载页上。本文走的是 API 这条路：你的代码、一个端点、一把 key。
第 1 步：拿到你的 String AI API key
用你的账号登录平台，打开仪表盘的 API keys 区，创建一个 key。key 属于你的账号，所以你在网页聊天里用的同一个登录就能管理它们。平台文档逐步讲解了账号设置与 key 创建；如果仪表盘在这篇文章写成之后挪过位置，就按它来。
拿到 key 之后，把它存到 shell 能读到的地方，而不是粘进源码文件：
export STRING_AI_API_KEY="YOUR_API_KEY"从此保持两个习惯。永远不要把真实 key 提交到仓库，也永远不要把它粘进截图、issue 或聊天消息。如果脚本需要 key，就让它读上面那个环境变量。本文所有示例都用占位符 YOUR_API_KEY，这样任何东西都不会被意外复制到生产环境。
第 2 步：把客户端指向 base URL
OpenAI 兼容的入口是：
https://www.string.ink/v1/v1 很重要。OpenAI 风格的客户端会拿这个 base URL 再追加自己的路径段，于是 chat 请求落到 /v1/chat/completions，模型查询落到 /v1/models。如果你把 base URL 设成裸的站点根地址，这些路径段就会落到错误的路径上，你会得到一个看起来像端点不存在的 404。平台把 base URL 固定在 https://www.string.ink/v1，并用 OpenAI Bearer token 认证兼容客户端，所以在 curl、SDK，以及那些要求填 OpenAI 兼容地址的工具设置里，要用的就是这个值。
在 OpenAI SDK 里，base URL 是构造函数的一个参数。在基于 shell 的工具里，它常常是一个环境变量。两者只是把同一个字符串送到同一个地方的不同方式。
第 3 步：先列出模型，再调用模型
不同账号可能有不同的模型权限，所以先从模型列表端点开始，而不是直接发 chat 请求。问 API 你的 key 实际能摸到什么：
curl https://www.string.ink/v1/models \
-H "Authorization: Bearer $STRING_AI_API_KEY"一个健康的响应包含 object "list" 和一个 data 数组，列出这个 key 可用的模型。仅这一次调用就同时证明三件事：key 有效、base URL 正确、网络路径通畅。模型 ID 也该从这里复制，而不是凭记忆敲。模型 ID 是精确字符串；猜一个的代价是一个模型找不到的错误，外加几分钟的困惑。
文档列出的例子包括 gpt-6-astra、gpt-5.6-luna 和 claude-opus-4-8，并建议先用更轻的 gpt-5.6-luna 验证连接，再切到你的工作负载需要的那个模型。把实时的模型列表当作权威来源，把这段文字当作指路。
第 4 步：发出你的第一个 chat completions 请求
key 与 base URL 都确认之后，第一个真正的请求是一段单轮对话。用 curl：
curl https://www.string.ink/v1/chat/completions \
-H "Authorization: Bearer $STRING_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-luna",
"messages": [
{"role": "user", "content": "Say hello in one sentence."}
]
}'请求体有三个活动部件：model 指定你在第 3 步复制的 ID，messages 承载对话（单条 user 消息是最小的合法形式），而端点讲的是OpenAI Chat Completions 格式，这意味着现有客户端和较旧的代码通常只需换掉 base URL 和 key 就能迁移。
如果你更想用OpenAI Python SDK，两个构造函数的值就能把它指向平台，而调用本身和你熟悉的一模一样：
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://www.string.ink/v1",
)
resp = client.chat.completions.create(
model="gpt-5.6-luna",
messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(resp.choices[0].message.content)对于需要边到边打印输出的聊天界面或命令行工具，在请求里加上 "stream": true。端点随后返回 Server-Sent Events：每个 chunk 携带 object "chat.completion.chunk"，增量文本出现在 choices[].delta.content 下，通常在流以 [DONE] 标记结束前，还会有一个 stats 块携带 usage。
第 5 步：读响应并核对用量
非流式响应遵循熟悉的 OpenAI 形状：一个 choices 数组，其中 choices[0].message.content 装着助手的文本；还有一个 usage 对象，报告这次请求的 token 数。先打印 content，并把 usage 留着；这是确认一次调用真的到达了模型的最快方式。
你的请求消耗会以绑定你账号的用量记录出现在平台仪表盘里，所以第一次成功调用之后，去那里找它。基础的用量追踪不需要任何配置；如果你之后轮换 key 或跑多个服务，记录就是分辨哪个 key 在干什么的依据。
在一切都还小的时候保持一个习惯：把第 4 步的最小 curl 命令留在草稿文件里。之后更大的应用里出问题时，先跑这个最小版本，大约十五秒就能把配置问题和代码问题分开。
让首次调用失败的三个错误
1. /v1 的约定并不通用。OpenAI 兼容调用要求 base URL 以 /v1 结尾。另一些工具对同一个平台用的是不同规则：Claude Code 的网关变量（ANTHROPIC_BASE_URL）取站点根地址，不带 /v1 后缀，因为那个客户端讲的是另一套协议，追加的是另一套路径。如果你要在两类工具之间来回工作，把两种约定分清楚，各自按该工具自己的文档页面来设。
2. 凭证必须出现在正确的 header 里。在 curl 和 SDK 里，key 以 Bearer token 的形式走在 Authorization header 里。两个经典失误：在一个终端里 export 了变量，却在另一个终端里跑 curl；以及给 header 的值套上单引号，这会让 shell 不再展开 $STRING_AI_API_KEY，于是字面文本 "Bearer $STRING_AI_API_KEY" 被发了出去。有些工具把自己的凭证称作“auth token”，并期望它放在自己特定的环境变量里；那只是工具约定，不是第二套凭证体系。收到 401 时，先看客户端实际发了什么，再怀疑 key。
3. 模型 ID 必须完全匹配，而且能力各不相同。一个拼写错误、一个过期的名字，或一个从别家借来的 ID，都会返回模型找不到，那是字符串问题而不是服务故障。也不要假设每个模型都接受相同的参数或相同的输入类型。文本与视觉输入、图片生成、图片编辑是由不同端点提供的；把图片 prompt 发给 chat 端点不是生成图片的办法。当某个模型拒绝某个参数时，去看模型列表和端点文档，而不是猜。
前三个错误码的快速排查
| What you see | Check first | Typical fix |
|---|---|---|
| 401 or 403 | The API key | Re-copy the key into the environment variable; confirm it is exported in the same shell you are calling from; remove stray quotes or whitespace; restart the client so it rereads its settings |
| 404 | The base URL | Make sure it is exactly https://www.string.ink/v1, with /v1 present once and no trailing path; check the request path for typos |
| model-not-found or parameter errors | The model ID and the endpoint | Copy the ID from the models list; confirm the model supports the input type you are sending and that you are calling the matching endpoint |
三行背后共同的原则：在把任何东西接进应用之前，先发一个最小请求。三十秒的 curl 会告诉你问题是 key、地址还是模型，而你在上面每加一层，故障可能长成的样子就先翻一倍。
接下来读什么
- 接入你的编码工具。关于用一把 key 跑 Codex CLI、Claude Code 和 Cursor的指南，从本文结束的地方接着讲。
- 为模型退役做规划。 迁移手册覆盖清点、别名层和预检，让一份退役通知永远不会变成一次故障。
- 把工作分给多个模型。 多模型工作流展示了如何把研究、写作和评审分配给不同的模型，而不增加协调工作。
- 安装桌面启动器。平台的下载页上有启动器，提供一条不用终端的配置路径。
范围与维护说明
本文描述的是路径和故障模式；精确的字段列表在平台文档里，会随平台演进变化。这里没有任何性能或可用性承诺，也没有引用定价或用量的数字，因为那些属于你的账号和当前文档。你的 API key 是整个流程里唯一的秘密：把它放在环境变量或密钥管理器里，拿不准时就轮换。
一次调用、一把 key、一个地址。先让最小请求跑通，之后的一切都是集成工作。