如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

速率限制

瞭解 API 的速率限制與使用限制。

速率限制是指 API 對使用者或用戶端在指定時間內可存取服務的次數所設的上限。

為什麼要設定速率限制?

設定速率限制是 API 的常見做法,原因如下:

  • 速率限制有助於防止 API 遭到濫用或誤用。 例如,惡意人士可能向 API 發送大量請求,企圖使其過載或干擾服務。OpenAI 可透過速率限制防止這類行為。
  • 速率限制有助於確保每個人都能公平使用 API。 如果某個人或組織發送過多請求,其他人使用 API 時也可能遇到延遲。OpenAI 藉由限制單一使用者可發送的請求數,讓盡可能多的人能順暢使用 API。
  • 速率限制有助於 OpenAI 管理基礎設施的整體負載。 API 請求量激增可能讓伺服器不堪負荷,影響效能。設定速率限制有助於 OpenAI 為所有使用者維持順暢、穩定的使用體驗。

請閱讀完整文件,以瞭解 OpenAI 的速率限制機制。本文提供程式碼範例與常見問題的可能解法。下方的使用層級一節也會說明速率上限如何自動調高。

速率限制如何運作?

速率限制採用的指標包括 RPM(每分鐘請求數)、RPD(每日請求數)、TPM(每分鐘 Token 數)、TPD(每日 Token 數)和 IPM(每分鐘圖片數)。部分串流音訊模型也會計算每分鐘可處理的音訊分鐘數。任一指標先達上限,就會觸及速率限制。例如,假設你的 RPM 上限為 20,TPM 上限為 150,000。即使你在一分鐘內向 ChatCompletions 端點發送的 20 個請求總共只有 100 個 Token,遠低於 150,000 個 Token,請求數仍已達到上限。

Batch API 的佇列上限按各模型佇列中的輸入 Token 總數計算。尚未完成的批次作業所含的 Token 都會計入佇列用量。批次作業一旦完成,其 Token 就不再占用該模型的佇列額度。

另請留意以下事項:

  • 速率限制適用於組織層級與專案層級,不會按個別使用者計算。
  • 速率限制因所使用的模型而異。
  • GPT-5.5 等支援長上下文的模型會對長上下文請求另設速率限制。你可以在開發人員主控台查看這些限制。
  • OpenAI 會為每個組織核定每月使用上限。此上限與你可以為組織或專案設定的支出上限分開計算。
  • 部分模型系列共用速率限制。組織限制頁面上列在同一個「共用上限」下的模型共用一個速率上限。例如,如果共用 TPM 上限為 350 萬,呼叫該「共用上限」清單中的任何模型,都會計入這 350 萬個 Token 的額度。
  • 將資料匯入向量儲存庫時,也會按向量儲存庫 ID 套用速率限制。每個向量儲存庫的 /vector_stores/{vector_store_id}/files 和 /vector_stores/{vector_store_id}/file_batches 共用每分鐘 300 個請求的上限。匯入大量資料時,建議使用 /vector_stores/{vector_store_id}/file_batches。

使用層級

三個付費使用層級分別為 Build、Launch 和 Grow。組織購買點數的累計金額每達到一個門檻,使用層級就會自動升級。層級越高,各模型的速率上限通常也越高。

使用層級說明各層級適用的速率限制。即使某個模型列在速率限制清單中,也不代表你的組織、專案或 API 金鑰有權存取該模型。如果找不到某個模型,請檢查模型可用性。

層級 資格條件 使用上限
免費 使用者必須位於支援的地區 每月 $100
Build 累計購買 $5 的點數 每月 $500
Launch 累計購買 $100 的點數 每月 $5,000
Grow 累計購買 $500 的點數 每月 $200,000

標準速率限制

若要查看目前使用層級中各模型的上限,請前往設定 > 組織 > 限制,查看速率限制。若要升級使用層級,請選取升級層級,此選項位於使用層級區段。

這些標準速率限制與超高速模式的速率限制不同。

層級模型RPMTPM
BuildAstra、Sol、Terra5,0001,000,000
Luna5,0002,000,000
LaunchAstra、Sol、Terra10,0004,000,000
Luna10,00010,000,000
GrowAstra、Sol、Terra15,00040,000,000
Luna30,000180,000,000

支出上限

你可以為組織或專案設定支出上限,以控管每月 API 支出。這些設定與上述每月使用上限各自獨立。

控管方式 達到設定金額時的行為 適用情境
支出提醒 發送通知,API 流量不中斷 追蹤支出,同時維持流量
強制支出上限 受影響的 API 請求會傳回 429 錯誤 強制執行組織或專案的每月支出上限

回應標頭中的速率限制資訊

除了在帳戶頁面查看速率限制,你也可以從 HTTP 回應標頭取得重要資訊,包括剩餘的請求數、Token 數及其他中繼資料。

回應可能包含下列標頭欄位:

欄位 範例值 說明
Retry-After 56 若有此欄位,其值表示遇到暫時性速率限制錯誤後,重試前至少須等待的秒數。
x-ratelimit-limit-requests 60 速率限制允許的請求總數上限。
x-ratelimit-limit-tokens 150000 速率限制允許的 Token 總數上限。
x-ratelimit-remaining-requests 59 達到速率上限前還可發送的請求數。
x-ratelimit-remaining-tokens 149984 達到速率上限前還可使用的 Token 數。
x-ratelimit-reset-requests 1s 距離請求數額度重設為初始值的時間。
x-ratelimit-reset-tokens 6m0s 距離 Token 額度重設為初始值的時間。
x-ratelimit-limit-project-tokens 60000 專案的 Token 上限。
x-ratelimit-remaining-project-tokens 57000 達到專案的 Token 速率上限前還可使用的 Token 數。
x-ratelimit-reset-project-tokens 3s 距離專案的 Token 額度重設為初始值的時間。

如果請求受專案層級的 Token 上限約束,回應可能會包含專案 Token 標頭。Retry-After 可能出現在暫時性速率限制引起的 429 回應,或模型暫時過載引起的 503 回應中。這個標頭並不表示重試就能解決配額、帳務或其他需要使用者處理的錯誤。

微調速率限制

你可以在控制台查看組織的微調速率限制,也可以透過 API 取得這些資訊:

curl https://api.openai.com/v1/fine_tuning/model_limits \
  -H "Authorization: Bearer $OPENAI_API_KEY"

模型可用性

模型存取權與速率限制各自獨立。達到使用層級的門檻,並不代表你就能存取所有模型。如果文件列出的模型未出現在 Playground 或 GET /v1/models 的回應中,或是請求傳回 model_not_found,請依序檢查:

  1. 檢查模型 ID 和端點。 請使用與模型文件完全相同的模型 ID,確認該模型支援你使用的端點,並查看是否有關於模型停用或可用性的公告。
  2. 核對組織、專案和憑證。 在 Playground 中選取你要使用的組織和專案。呼叫列出模型時,請使用與失敗請求相同的 API 金鑰。如果該請求包含 OpenAI-Organization 或 OpenAI-Project 標頭,也請帶入相同的標頭和值。即使你登入控制台後看得到某個模型,使用其他 API 金鑰時仍可能無法存取該模型。
  3. 檢查專案限制與模型要求。 請有權管理該專案的人員檢查專案的模型權限與資料保留設定。請依照該模型的存取要求辦理,並查看模型文件中是否有分階段開放的公告。僅憑模型未出現在清單中,無法判斷原因。
  4. 重新整理後再檢查一次。 變更存取設定後,請重新整理模型清單或 Playground。如果仍無法使用該模型,請聯絡支援團隊,並提供模型 ID、組織 ID、專案 ID、發送請求的時間和錯誤訊息。如果回應包含 x-request-id 標頭,也請提供其值。請勿分享你的 API 金鑰。

減輕錯誤的影響

處理流量激增與模型過載

當請求速率上升過快時,API 可能會傳回 slow_down。當請求使用的模型暫時過載時,API 可能會傳回 server_is_overloaded。請檢查 HTTP 狀態碼和 error.code 以區分這兩種情況:

HTTP 狀態碼 錯誤類型 錯誤碼 含義 處理方式
429 rate_limit_error slow_down 請求速率上升過快。 若有 Retry-After,請依其指定的時間等待,降低請求速率,再逐步調高。
503 service_unavailable_error server_is_overloaded 請求使用的模型暫時過載。 若有 Retry-After,請依其指定的時間等待後再重試。如果錯誤持續發生,請拉長重試間隔。

如果沒有 Retry-After,請拉長重試間隔,並額外加入一小段隨機延遲。

即使流量未超過每分鐘請求數和每分鐘 Token 數的上限,仍可能出現 slow_down 錯誤。這個錯誤反映的是流量增加的速度,與是否用盡這些額度無關。

一般而言,流量一旦達到每分鐘 100 萬個輸入 Token(TPM),之後每 15 分鐘的增幅就應控制在 50% 以內。實際開始限制流量增速的門檻可能因模型和流量狀況而異。

若企業客戶的隨用隨付流量經常觸及流量增速上限,可以考慮使用規模層級,讓適用模型的可用容量更容易預估。如使用 GPT-5.6 或後續模型,請參閱預留層級。不論採用哪種容量層級,處理 slow_down 回應的方式都相同:若有 Retry-After,請依其指定的時間等待,降低流量,再逐步增加。

更新現有的錯誤處理程式

如果你的應用程式已有處理舊版限流與過載回應的邏輯,請同時檢查 HTTP 狀態碼和 error.code:

  • 部分端點過去在這兩種情況下都會傳回 503 和錯誤碼 slow_down。現在,流量上升過快時會傳回 429 和 slow_down。模型過載時仍會傳回 503,但錯誤碼改為 server_is_overloaded。
  • 過去,影片請求若因上述情況而在建立作業前遭拒,會傳回 429,錯誤類型為 invalid_request_error,錯誤碼為 rate_limit_exceeded。現在,流量上升過快時會傳回 429、rate_limit_error 和 slow_down。模型過載時則會傳回 503、service_unavailable_error 和 server_is_overloaded。影片作業狀態中回報的錯誤屬於另一種情況。

請在 SDK 錯誤處理程式中同時處理 429 和 503。例如,Python、TypeScript 和 Ruby 以 RateLimitError 表示 429,以 InternalServerError 表示 503。Java 則分別使用 RateLimitException 和 InternalServerException。只要應用程式仍可能收到舊版回應碼,就應保留相應的處理邏輯。其他錯誤也可能使用相同的 HTTP 狀態碼,因此請先檢查錯誤回應本文,再決定如何復原。

對於串流請求,這些 HTTP 錯誤回應適用於串流開始前。串流開始後,錯誤可能會以串流事件的形式送達。如果已讀取輸出,請勿自動重新發送請求。

可以採取哪些措施減輕影響?

OpenAI Cookbook 提供 Python 筆記本,說明如何避免速率限制錯誤,也提供 Python 指令碼範例,示範如何批次處理 API 請求而不超過速率上限。

提供程式化存取、大量處理或自動在社群媒體發文的功能時,也請謹慎評估。建議只對可信任的客戶開放這些功能。

為防範自動化和大規模濫用,請為個別使用者設定指定期間內的使用上限,例如每日、每週或每月上限。對於超過上限的使用者,可考慮強制限制用量或啟動人工審查流程。

以指數退避方式重試

當請求超過暫時性速率上限時,API 會傳回 429 錯誤。回應可能包含 Retry-After 標頭,指出重試前要等待的秒數。請至少等待指定的時間,再額外加入一小段隨機延遲,以免多個用戶端同時重試。

每個 OpenAI 官方 SDK 都會依據重試設定,自動重試符合條件的 429 和 503 回應。各 SDK 版本與設定處理 Retry-After 的方式可能不同,尤其是等待時間較長時。請確認已安裝版本的重試行為,不要假設它支援伺服器指定的所有等待時間。

如果伺服器指定的等待時間有效,但超過支援或設定的重試等待上限,請停止重試並延後處理該請求,切勿提早重試。SDK 若不接受超過上限的等待時間,可能會傳回原始 HTTP 錯誤。請繼續分別處理取消和逾時錯誤:請求遭取消或已過截止時間,都可能使重試停止,而不傳回該 HTTP 錯誤。單次嘗試的逾時設定不一定會限制整個操作的總時間。

如果使用自己的 HTTP 用戶端,當回應包含 Retry-After 標頭且其值有效時,請依其指定的時間等待。如果標頭缺漏或值無效,請改用帶有隨機抖動的指數退避。同時限制嘗試次數與重試總時間。如果由應用程式管理重試,請停用 SDK 的重試功能,或將 SDK 的重試也計入上述限制,以免巢狀重試迴圈讓請求數倍增。遇到配額、帳務或其他需要你採取行動才能解決的錯誤時,請勿重試。

指數退避是指在請求失敗後先短暫等待,再於每次重試失敗後按指數增加等待時間,直到請求成功或達到設定的重試上限。

這種做法有幾項好處:

  • 自動重試可讓應用程式從速率限制錯誤中復原,避免當機或遺漏資料。
  • 指數退避可讓前幾次重試迅速進行。如果這些嘗試失敗,後續重試仍可拉長等待時間。
  • 在等待時間中加入隨機抖動,有助於錯開各個請求的重試時間。

請注意,失敗的請求也會計入每分鐘用量,因此不斷重新發送請求無法解決問題。

下列範例示範如何重試使用 gpt-6-luna 的 Responses API 請求。每個包裝函式都會限制嘗試次數,並停用 SDK 內建的重試功能。

下方的 Python 範例示範如何在無法取得有效等待時間時使用退避機制。這些範例不會檢查 Retry-After。使用前,請先加入處理伺服器有效等待時間的邏輯,避免包裝函式提早重試。請停用 SDK 的重試功能,或將 SDK 的重試計入應用程式的重試上限。

調低 max_tokens 以符合預期的回應長度

計算速率限制用量時,系統會比較 max_tokens 與根據請求字元數估算的 Token 數,並採用兩者中較大的值。請盡量將 max_tokens 設為接近預期回應長度的值。

批次處理請求

如果你的使用情境不需要立即取得回應,可以使用 Batch API 提交並執行大批請求,不會占用同步請求的速率額度。

如果你的使用情境 確實 需要同步回應,OpenAI API 會分別限制每分鐘請求數和每分鐘 Token 數。

如果每分鐘請求數已達上限,但每分鐘 Token 額度仍有餘裕,可以在每個請求中合併多項任務,以提高吞吐量。這樣每分鐘就能處理更多 Token,使用較小的模型時尤其有效。

批次發送提示詞的方式與一般 API 呼叫相同,差別只在於傳給 prompt 參數的是字串清單,而非單一字串。如需詳細說明,請參閱 Batch API 指南。