用 OpenAI SDK 接入 | 土土金 API 文件

OpenAI 官方 SDK 只要改兩個參數就能用：base_url 設為 https://www.tutujin.com/v1，api_key 換成土土金的 Key。同一個 client 可以呼叫對話、Responses、向量、影像和語音介面；換模型只改 model 參數，GPT 以外的 Claude、Gemini、DeepSeek 等目錄裡支援 Chat Completions 的模型也能這樣呼叫。

安裝

pip install openai

npm install openai

建立 client

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://www.tutujin.com/v1",
    api_key=os.environ["TUTUJIN_API_KEY"],
)

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://www.tutujin.com/v1',
  apiKey: process.env.TUTUJIN_API_KEY,
})

也可以不改程式碼，只設置環境變數：SDK 預設會讀取 OPENAI_BASE_URL 和 OPENAI_API_KEY。

cURL

export OPENAI_BASE_URL="https://www.tutujin.com/v1"
export OPENAI_API_KEY="sk-你的Key"

對話

resp = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[
        {"role": "system", "content": "你是一名简洁的助理。"},
        {"role": "user", "content": "用三句话解释什么是 RAG。"},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)  # 本次的输入、输出 tokens

const resp = await client.chat.completions.create({
  model: 'gpt-5.4-mini',
  messages: [
    { role: 'system', content: '你是一名简洁的助理。' },
    { role: 'user', content: '用三句话解释什么是 RAG。' },
  ],
})
console.log(resp.choices[0].message.content)
console.log(resp.usage) // 本次的输入、输出 tokens

參數說明見 Chat Completions。

流式輸出

stream = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "写一段 100 字的产品介绍"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

const stream = await client.chat.completions.create({
  model: 'gpt-5.4-mini',
  messages: [{ role: 'user', content: '写一段 100 字的产品介绍' }],
  stream: true,
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '')
}

向量

emb = client.embeddings.create(
    model="text-embedding-3-small",
    input=["退货政策是什么？", "多久发货？"],
)
print(len(emb.data), len(emb.data[0].embedding))

const emb = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: ['退货政策是什么？', '多久发货？'],
})
console.log(emb.data.length, emb.data[0].embedding.length)

input 傳陣列可以一次處理多條文本，比逐條請求更快，也不容易觸發限流。

呼叫其他廠商的模型

client 不用變，只換 model。目錄裡標註支援 Chat Completions 的模型都可以這樣呼叫：

Python

for model in ["claude-sonnet-5-5", "deepseek-v4.1-flash"]:
    resp = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": "你好"}],
    )
    print(model, resp.choices[0].message.content)

不同廠商對可選參數的支援不完全一樣。需要 Claude 原生功能時，改用 Anthropic SDK 呼叫原生 Messages 介面。

超時與重試

SDK 遇到 429、5xx 和網路錯誤會自動重試，預設 2 次。生產環境建議按業務調整重試次數和超時：

client = OpenAI(
    base_url="https://www.tutujin.com/v1",
    api_key=os.environ["TUTUJIN_API_KEY"],
    max_retries=4,
    timeout=60.0,  # 秒
)

const client = new OpenAI({
  baseURL: 'https://www.tutujin.com/v1',
  apiKey: process.env.TUTUJIN_API_KEY,
  maxRetries: 4,
  timeout: 60_000, // 毫秒
})

注意：餘額不足返回 403，SDK 不會重試它，需要你在程式碼裡單獨提醒。完整說明見錯誤碼與重試。

非同步呼叫（Python）

併發處理大量請求時用 AsyncOpenAI，參數和同步版一樣：

Python

import asyncio
import os

from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="https://www.tutujin.com/v1", api_key=os.environ["TUTUJIN_API_KEY"])


async def main():
    resp = await client.chat.completions.create(
        model="gpt-5.4-mini",
        messages=[{"role": "user", "content": "你好"}],
    )
    print(resp.choices[0].message.content)


asyncio.run(main())

併發上限怎麼設，見限流說明。

常見問題

現象	原因與處理
404	`base_url` 少了 `/v1`，應為 `https://www.tutujin.com/v1`
401	Key 填錯或已失效，確認讀取的環境變數裡是完整的 Key
503 並提示 `model_not_found`	Key 所在分組沒有這個模型，換分組或核對模型名，見選擇分組
返回很慢或超時	長輸出開啟流式，並適當調大 `timeout`

沒找到答案？加客服微信 JsnonoChat，傳送報錯資訊裡的 request id，我們幫你排查。