第一次成功呼叫 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、一個地址。先讓最小請求跑通，之後的一切都是整合工作。