通用約定

瞭解 AGTCloud API 的節點、位址、身分驗證、內容型別、回應處理和錯誤復原規則。

本頁說明 AGTCloud API 各端點共同使用的呼叫規則。特定欄位、狀態和回應結構仍以對應的 API Reference 頁面為準。

API 位址與 Base URL

本頁使用的 API 位址為 https://api.agtcloud.cn，OpenAI 相容 SDK 使用的 Base URL 為 https://api.agtcloud.cn/v1。

使用情境	位址組成	範例
原始 HTTP 請求	API 位址 + 完整 Endpoint Path	`https://api.agtcloud.cn` + `/v1/chat/completions`
OpenAI 相容 SDK	Base URL + SDK 方法對應路徑	`https://api.agtcloud.cn/v1`
Realtime WebSocket	WebSocket 節點 + 連線路徑	`wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID`

避免重複串接 /v1

https://api.agtcloud.cn/v1 已包含 /v1。使用相容 SDK 時，請勿再手動將 /v1 加入 SDK 方法生成的路徑，否則請求可能會變成 /v1/v1/...。

身分驗證

大多數受保護的 API 使用 Bearer API Key：

Authorization: Bearer your-api-key

Anthropic Messages 使用專屬驗證 Header，並要求提供 API 版本：

x-api-key: your-api-key
anthropic-version: 2023-06-01

anthropic-beta 等選用 Header 和其他協議的身分驗證要求，以對應的 Endpoint 頁面為準。

前往 API Keys 建立和管理權杖。呼叫時只傳送 API Key，請勿使用控制台密碼、Cookie、管理員權杖或上游供應商 Key。

以下是最小的 Chat Completions 請求：

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  --request POST \
  --header 'Authorization: Bearer your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      }
    ]
  }'

API Key 的建立、輪替和正式環境儲存方式請參閱 API Key、Base URL 與身分驗證。

請求參數放在哪裡

端點頁面會依參數所在位置分別顯示欄位：

參數位置	用途	範例
Path Parameters	識別特定資源或任務	`/v1/videos/{video_id}`
Query Parameters	控制篩選、變體或輸出形式	`?variant=video`
Headers	傳遞身分驗證和內容協商資訊	`Authorization`、`x-api-key`、`Content-Type`
Request Body	傳遞模型、輸入和生成參數	JSON 或 Multipart 表單

Path 參數必須先進行 URL 編碼。選用參數未使用時應省略，請勿使用空字串代替所有選用值。

Content-Type 與資料格式

資料形式	常見 Content-Type	處理方式
JSON 請求和回應	`application/json`	序列化請求物件並解析 JSON
檔案與表單上傳	`multipart/form-data`	由 HTTP 用戶端生成 Multipart 邊界
SSE 串流	`text/event-stream`	依事件邊界持續讀取資料
SDP	`application/sdp`	用於部分即時連線協商
二進位檔案	`video/mp4`、音訊媒體型別等	讀取位元組串流並儲存或轉送

使用 Multipart 時請勿手動寫死 boundary；應由瀏覽器、SDK 或 HTTP 用戶端依表單內容生成完整的 Content-Type。

模型 ID

Reference 範例中的 MODEL_ID 是預留位置，必須替換為目前 API Key 可以使用的模型 ID。可以前往模型廣場尋找模型，也可以在 Try It 中填入 Key 後取得該 Key 傳回的模型清單。

模型、協議和上游供應商是不同概念：

模型 ID 決定請求的目標模型。
Endpoint 決定用戶端使用的協議和訊息結構。
同一模型可能提供多個協議入口，也可能只支援部分欄位。

解析回應

處理回應時，建議依照以下順序：

讀取 HTTP 狀態

先判斷請求是否成功，再決定解析成功物件或錯誤資訊。請勿只依據回應本文中的單一欄位判斷結果。

檢查 Content-Type

依實際媒體型別選擇 JSON、SSE、文字或二進位解析器。下載 API 不能強制以 JSON 解析。

依特定協議讀取欄位

Chat 通常傳回 choices，Responses、Gemini、非同步任務和 WebSocket 使用不同結構。用戶端不應假設所有 API 共用同一種回應物件。

儲存追蹤資訊

儲存請求時間、Method、Path、模型和 HTTP 狀態。回應中存在 Request ID 時一併儲存，但請勿記錄完整 API Key 或敏感輸入。

串流回應

SSE API 會在單一 HTTP 回應中持續傳送多個事件或資料區塊。用戶端必須增量讀取內容，而不是等待連線關閉後再將整個回應解析為單一 JSON 物件。

依端點說明識別結束事件或結束標記。
分別處理內容增量、工具呼叫、Usage 和錯誤事件。
網路中斷時，請勿預設已收到的內容是完整結果。
不同協議的串流事件結構不同，應使用目前端點的事件定義。

非同步任務

影片、Midjourney 等 API 通常會先傳回任務識別碼，再透過查詢 API 取得進度與最終結果：

提交任務 → 儲存任務 ID → 查詢狀態 → 判斷終止狀態 → 讀取結果

任務 ID 的欄位名稱、狀態列舉和查詢路徑由特定協議決定。請勿在不同 API 間混用 id、task_id、video_id 或狀態值。

輪詢時應設定查詢間隔與總逾時，並在任務成功、失敗或取消後停止。提交請求逾時但任務可能已經建立時，應先確認任務狀態，避免重複建立付費任務。

HTTP 狀態與重試

以下是通用處理方向，特定錯誤結構以端點實際回應為準：

HTTP 狀態	常見含義	建議處理
`400`	請求格式、欄位或欄位組合無效	修改請求後再傳送
`401`	API Key 缺少、無效或驗證 Header 格式錯誤	檢查身分驗證資訊和 Key 狀態
`403`	目前帳戶、Key 或資源權限不足	檢查節點、權限和帳戶狀態
`404`	路徑、模型、任務或資源不存在	檢查 URL、模型 ID 和資源 ID
`429`	請求受到頻率、並行數或額度限制	依回應資訊等待後進行有限次重試
`5xx`	平台或上游服務暫時異常	使用退避策略進行有限次重試

請勿對所有錯誤無限重試。參數、身分驗證和權限問題只有修正後才適合重新傳送；建立任務等可能產生副作用的請求，應先判斷是否已成功提交。

更完整的診斷步驟請參閱錯誤與疑難排解。

Usage、時間和擴充欄位

Usage 欄位是否存在及其名稱由特定協議和模型決定，用戶端應允許其為空值或缺少。
時間欄位可能使用 Unix 秒、Unix 毫秒或字串時間，必須依端點 Schema 解析。
供應商擴充欄位通常只對部分模型生效，不應視為所有模型的共同功能。
用戶端解析回應時應允許新增的非關鍵欄位，避免平台增加相容欄位後造成整體解析失敗。

安全性與日誌

長期 API Key 應儲存在可信任的伺服器端或金鑰管理系統中，正式環境前端、桌面端和行動用戶端不得內建 Key。
文件 Try It 僅供客戶主動發起的臨時瀏覽器測試，請勿在共用裝置上使用長期正式環境 Key。
請勿將 Key 寫入公開程式碼儲存庫、截圖、日誌或支援單。
疑難排解資料應對 Prompt、檔案位址、帳戶資訊和請求回應中的敏感資料進行遮蔽處理。
不再使用或疑似外洩的 Key 應立即停用或刪除，並更新使用該 Key 的服務。

繼續閱讀：API Reference · 快速開始 · 錯誤與疑難排解

本頁目錄