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 表示最多接受官方价的 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,响应已开始时结束流。