APIMaster.ai

請求層級路由控制

透過選用的 HTTP 請求標頭,為單次文字生成設定官方價格比例、重試次數與總時限。

請求層級路由控制

指定或排除渠道

文字、圖片和影片生成請求可設定渠道範圍。兩個請求標頭可同時使用,排除規則優先。

  • X-APIMaster-Include-Channels · 僅允許列出的渠道。
  • X-APIMaster-Exclude-Channels · 排除列出的渠道。

每個請求標頭最多接受 64 個以逗號分隔的正整數。依模型查詢公開渠道的 channel_id。實際可用範圍依 API Key 與控制台規則而定。渠道也必須支援本次請求的操作與參數。

curl "https://apimaster.ai/api/public/marketplace?model=deepseek-flash"

重試和備援都遵守本次範圍。非同步生成會保留範圍,支援冪等提交的介面會把範圍納入冪等檢查。

格式錯誤會回傳 400 invalid_routing_parameter。沒有符合範圍的渠道時回傳 503 no_provider_within_channel_scope。查詢及下載既有任務時沿用原渠道。

查詢及下載既有結果時無須傳送此兩個標頭。不支援的介面或託管 FreeModel 集區收到標頭時會回傳 400 routing_controls_unsupported。

生成範例

curl "https://apimaster.ai/v1/chat/completions" \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-APIMaster-Exclude-Channels: $TEXT_CHANNEL_ID" \
  -d '{"model":"deepseek-flash","messages":[{"role":"user","content":"Reply with OK."}]}'

curl "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-APIMaster-Include-Channels: $IMAGE_CHANNEL_ID" \
  -d '{"model":"gpt-image-2","prompt":"A blue ceramic cup on a white table","size":"1024x1024"}'

curl "https://apimaster.ai/v1/videos" \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-APIMaster-Include-Channels: $VIDEO_CHANNEL_ID" \
  -d '{"model":"wan3.0-video-prime","prompt":"A flower sways in a light breeze","duration":2,"resolution":"480P"}'

文字價格、重試和時限

透過選用的 HTTP 請求標頭,為單次文字生成設定官方價格比例、重試次數與總時限。

請求標頭 說明
X-APIMaster-Max-Official-Price-Ratio 可接受的最高官方價格比例。填入正數,0.5 代表最多接受官方價格的一半,1 代表最多接受官方原價。
X-APIMaster-Max-Retries 首次送出後允許的額外上游嘗試次數。填入非負整數,0 代表只送出一次。切換供應商與官方備援都計入。
X-APIMaster-Timeout-Ms 總時限,填入正整數,單位為毫秒。從閘道收到請求起算,包含路由選擇、重試與串流。平台時限較短時採用較短值。

各標頭可單獨使用。省略的項目沿用現有策略,控制台的供應商設定仍適用。價格上限檢查輸入、輸出與適用的快取單價,總費用依實際用量而定。開始串流生成內容後,閘道不會切換供應商重新生成。

適用端點

  • POST /v1/chat/completions
  • POST /v1/responses
  • POST /v1/messages
  • POST /v1beta/models/{model}:generateContent
  • POST /v1beta/models/{model}:streamGenerateContent

此功能適用於文字生成。圖片、影片與其他未涵蓋的端點收到這些標頭時回傳 400 routing_controls_unsupported。工具呼叫等另行收費項目不計入文字單價上限。

範例

curl https://apimaster.ai/v1/chat/completions \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-APIMaster-Max-Official-Price-Ratio: 0.5" \
  -H "X-APIMaster-Max-Retries: 1" \
  -H "X-APIMaster-Timeout-Ms: 30000" \
  -d '{"model":"gpt-6.2-sol","messages":[{"role":"user","content":"Reply with OK."}]}'

錯誤

參數無效時回傳 400 invalid_routing_parameter。無可驗證的官方基準時回傳 400 official_price_unavailable。無供應商符合價格上限時,送出前回傳 503 no_provider_within_price_limit。逾時時,尚未開始回應則回傳 504 request_deadline_exceeded,已開始串流則結束串流。