快速開始

5 分鐘快速接入

Aiaimark 提供 OpenAI 兼容的 API。只需創建密鑰、選擇模型並修改 Base URL，即可在現有項目中使用平臺上的主流大模型。

預計用時：5 分鐘適用於：首次接入用戶

準備工作

開始前準備

一個可用的 Aiaimark 賬號賬戶中有可用額度能夠發送 HTTPS 請求的開發環境

賬號

註冊並登錄平臺

首次使用請先註冊賬號。註冊完成後登錄控制台，確認賬戶狀態正常並有足夠的可用額度。

註冊賬號登錄控制台

鑑權

創建 API Key

進入控制台的 API Key 管理頁面，創建一個新密鑰並立即保存。密鑰只應存放在服務端環境變量中，不要寫入前端代碼或提交到代碼倉庫。

妥善保管你的密鑰

建議按項目分別創建密鑰。若密鑰意外洩露，請立即在控制台刪除並重新創建。

模型

選擇可用模型

前往模型廣場查看當前可用模型及價格，複製你要調用的準確模型名稱，並將它填入請求中的 model 字段。

查看模型廣場

API 請求

發起第一次對話請求

平臺接口兼容 OpenAI 請求格式。將示例中的 API Key 和模型名稱替換為你的實際值後，即可發送請求。

Base URL: https://ai.aiaimark.com/v1
接口地址: https://ai.aiaimark.com/v1/chat/completions
鑑權方式: Authorization: Bearer sk-your-api-key

cURL終端

curl https://ai.aiaimark.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "messages": [
      { "role": "user", "content": "你好，請介紹一下你自己" }
    ]
  }'

請求成功後，模型回覆位於 choices[0].message.content。如果收到 401，請檢查 API Key；如果提示模型不存在，請重新複製模型廣場中的模型名稱。

SDK

接入你的應用

現有 OpenAI SDK 只需替換 baseURL 和 API Key 即可接入。以下是 Node.js 示例：

JavaScriptOpenAI SDK

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.AIAIMARK_API_KEY,
  baseURL: 'https://ai.aiaimark.com/v1',
})

const response = await client.chat.completions.create({
  model: 'YOUR_MODEL_NAME',
  messages: [{ role: 'user', content: '你好，請介紹一下你自己' }],
})

console.log(response.choices[0].message.content)

接入完成

現在可以根據業務需要調整模型、消息內容和生成參數。上線前請為請求添加超時、重試與錯誤日誌。

Codex

在 Codex 中使用 Aiaimark

Codex 支持自定義模型 Provider。將 Aiaimark 配置為 Provider 後，Codex CLI、桌面端和 IDE 擴展即可通過平臺調用支持 Responses API 的模型。

兩種接入方式，任選一種

推薦使用 CC Switch，跟著截圖即可完成配置。也可以選擇手動配置，兩種方式任選一種，無需重複操作。

選擇模型在模型廣場複製一個支持 Responses API 與工具調用的模型名稱，用它替換下方的 YOUR_CODEX_MODEL。
編輯用戶配置打開用戶目錄下的 ~/.codex/config.toml；Windows 通常位於 %USERPROFILE%\.codex\config.toml。
添加 Provider把以下配置加入文件。如果已有其他配置，請保留原內容併合並這些字段。

config.tomlCodex Provider

model = "YOUR_CODEX_MODEL"
model_provider = "aiaimark"

[model_providers.aiaimark]
name = "Aiaimark"
base_url = "https://ai.aiaimark.com/v1"
env_key = "AIAIMARK_API_KEY"
wire_api = "responses"

請使用用戶級配置

Provider 與鑑權配置必須放在用戶級 ~/.codex/config.toml，Codex 不會從項目內的 .codex/config.toml 讀取這些字段。

設置密鑰並啟動不要把密鑰直接寫入配置文件。先設置環境變量，再從同一終端啟動 Codex。

Terminal啟動命令

# macOS / Linux（在啟動 Codex 的同一終端執行）
export AIAIMARK_API_KEY="sk-your-api-key"
codex

# Windows PowerShell
$env:AIAIMARK_API_KEY="sk-your-api-key"
codex

開始使用 Codex

啟動後確認當前模型為配置中的模型，然後打開項目併發起任務。如果遇到 401，請檢查環境變量；如果模型不可用，請更換模型廣場中的模型名稱。

查看 Codex 官方配置文檔

推薦方式 · 圖形界面

使用 CC Switch 接入 Codex

CC Switch 是第三方開源配置管理工具，方便在圖形界面中添加和切換 Codex 供應商。選擇此方式後，按以下步驟完成即可，無需再做手動配置。

以下為 CC Switch 4.0.15 中文界面的實際截圖，紅框數字對應操作位置，點擊圖片可放大。配置截圖使用示例密鑰和模型佔位符，使用時請替換為自己的真實值；餘額已遮蓋。

安裝並打開 CC Switch從 CC Switch 官網下載適合系統和芯片架構的安裝包：Windows 使用 MSI 或便攜版 ZIP，macOS 使用 DMG，Linux 使用 DEB、RPM 或 AppImage。請先確認本機已安裝 Codex，並準備好 Aiaimark API Key、可用額度和支持 Responses API 與工具調用的模型名稱。

下載 CC Switch 查看 CC Switch 官方教程

macOS已安裝 Homebrew 時也可使用

brew install --cask cc-switch

添加自定義供應商在 CC Switch 中選擇 Codex，點擊右上角「+ / 添加供應商」，再選擇「自定義配置」。若界面提供「直連 / 路由 / 聚合」標籤，本教程使用「直連」模式。不同版本的按鈕名稱可能略有差異。

圖 1：先選左側 Codex（①），進入添加供應商後選擇「自定義配置」（②）。查看大圖

填寫 Aiaimark 連接信息按下方對應關係填寫表單。API Key 使用控制台創建的真實密鑰；模型名從模型廣場複製，不要直接使用示例佔位符。

圖 2：填寫名稱（①）、API Key（②）、API 請求地址（③）和默認模型（④）。查看大圖

供應商名稱: Aiaimark
請求地址 / Base URL: https://ai.aiaimark.com/v1
API Key: 你在 Aiaimark 控制台創建的密鑰
默認模型: YOUR_CODEX_MODEL（替換為實際模型名稱）
上游格式: Responses（原生）

名稱填 Aiaimark，備註可以留空；「官網鏈接」只是快捷入口，可以填 https://aiaimark.com，它不能代替「API 請求地址」。將控制台創建的完整密鑰粘貼到 API Key，不要加 Bearer 前綴或引號。

「API 請求地址」必須填 https://ai.aiaimark.com/v1，保留 /v1，不要追加 /responses 或 /chat/completions。上方表單填好後，下方 auth.json 和 config.toml 會自動更新，通常無需再手改這兩塊內容。

設置模型和接口格式在「模型列表」點擊「手動添加」，將「菜單顯示名」和「實際請求模型」都填為模型廣場中支持 Responses API 與工具調用的準確名稱。截圖裡的 YOUR_CODEX_MODEL 只是佔位符。

圖 3：模型列表填真實模型名（①）；高級選項使用 Responses（原生）（②），完整 URL 保持關閉。查看大圖

列表第一行就是默認模型；添加列表後，單獨的「默認模型」輸入框可能不再顯示。也可以先點「獲取模型列表」再選擇模型；如果獲取失敗，使用手動添加即可。上下文窗口、思考等級和子代理模型不確定時保持默認。

展開「高級選項」，核對上游格式為「Responses（原生）」，「完整 URL」關閉。按本教程選擇支持原生 Responses 的模型即可直連，不需要為了接入而額外開啟路由或聚合。

CC Switch 會保存密鑰並在啟用供應商時寫入本機配置，請勿分享包含真實密鑰的截圖或配置導出文件。已有手動配置時，先備份；如果編輯器中保留了上一節的 env_key，請移除該字段或確保對應環境變量與這裡的密鑰一致。

先保存配置核對名稱、密鑰、請求地址和模型後，點擊頁面右下角橙色的「添加」按鈕；編輯已有供應商時按鈕可能叫「保存」。返回列表，找到剛剛創建的 Aiaimark 卡片。供應商多時可以用右上角搜索。

保存配置 ≠ 已啟用

看到 Aiaimark 出現在列表中，只說明配置已保存。繼續完成下一步，讓 Codex 實際使用它。

在供應商列表啟用 Aiaimark進入 Codex 的「直連」頁，找到 Aiaimark 卡片。將鼠標移到卡片右側的插頭圖標，確認提示為「切換」後點擊；舊版可能直接顯示「啟用」。鉛筆圖標是編輯配置，不是啟用。

圖 5：直連頁籤（①）、卡片右側的切換入口（②）；截圖來自已有路由的環境，所以額外顯示「回到直連」（③）。查看大圖

如果界面像圖 5 一樣提示「你在查看直連，Codex 目前是路由」，僅點擊頁籤還沒有切換模式。此時 Aiaimark 卡片的插頭入口提示為「回到直連並使用」；點擊後才會切回直連並選用它。首次使用、已經處於直連的用戶不需要處理這一項。

切換後查看 Aiaimark 卡片是否出現「使用中」或當前供應商標識。圖 5 的「直連時使用」只表示路由開啟前的直連配置，不代表當前已經直連。

已經在用路由模式？如何確認當前供應商

如果你主動保留路由模式，在「路由」頁對 Aiaimark 點擊「路由到此」。圖 6 展示的是路由模式的狀態示例：頂部「路由生效中 → AIAIMark」與卡片「路由中」指向同一家，才說明路由選擇正確。直連用戶無需開啟路由來得到相同畫面。

圖 6：已有路由環境的狀態示例，頂部供應商（①）與卡片「路由中」（②）一致；這不是直連成功截圖。查看大圖

使用路由模式時需保持 CC Switch 運行；直連模式下，請求直接發往 Aiaimark。無論哪種模式，切換供應商或模型後都建議重啟 Codex 再驗證。

重啟 Codex 並驗證切換配置不會讓已打開的 Codex 會話自動重新加載。請按你使用的客戶端完成重啟，然後新建會話測試。

Codex CLI: 退出當前 Codex 進程，在項目目錄重新運行 codex；可以用 /model 核對當前模型。
Codex 桌面端: 徹底退出應用後重新打開。macOS 使用 ⌘Q，僅關閉窗口不算退出；Windows 使用應用的退出操作。
IDE 擴展: 關閉並重新打開 IDE 窗口，或執行重新加載窗口，再打開 Codex 擴展的新會話。

發送一句「你好，請介紹一下你自己」，確認收到回覆，再到 Aiaimark 控制台查看相同時間的調用記錄與模型名稱。兩處都能對應上，才算驗證完成；測速成功或看到卡片高亮，都不能代替這一步。

CC Switch 接入常見問題

401 / 鑑權失敗：重新核對 API Key 是否完整、有效，並檢查舊配置中的環境變量是否仍在覆蓋密鑰。
404 / 模型不可用：核對 Base URL 與模型名稱，確認所選模型支持 Responses API 與工具調用。
切換後沒有生效：確認已點擊「切換 / 啟用」並重啟 Codex；若使用 WSL、自定義配置目錄或多套 Codex 環境，確認 CC Switch 管理的是實際運行環境的配置。

以後如何切換或恢復

以後可以在 CC Switch 中選擇其他已保存的供應商，點擊「切換 / 啟用」並重啟 Codex。要恢復原配置，選擇之前保存的供應商；要恢復官方登錄，選擇 OpenAI 官方供應商，再按 Codex 的提示登錄。