Per-request routing controls
Set an official-price ceiling, retry limit, or deadline for a text generation request using optional HTTP headers.
Per-request routing controls
Include or exclude channels
Set the channel scope for a text, image, or video generation request. You can use both headers together. Exclusions take precedence.
X-APIMaster-Include-Channels· Allow only the listed channels.X-APIMaster-Exclude-Channels· Exclude the listed channels.
Each header accepts up to 64 comma-separated positive integers. Look up the model’s public channel_id values. Your API key and console preferences determine which channels are eligible. A channel must also support the operation and parameters in your request.
curl "https://apimaster.ai/api/public/marketplace?model=deepseek-flash"
All retries and fallbacks honor the request scope. Async generation preserves it, and endpoints that support idempotent submission include it in the idempotency check.
Invalid headers return 400 invalid_routing_parameter. If no channel matches your scope, the API returns 503 no_provider_within_channel_scope. Polling and downloads use the channel associated with the existing task.
Omit these headers when polling or downloading an existing result. Unsupported endpoints and the managed FreeModel pool return 400 routing_controls_unsupported.
Generation examples
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"}'
Text pricing, retries, and deadlines
Set an official-price ceiling, retry limit, or deadline for a text generation request using optional HTTP headers.
| Header | Behavior |
|---|---|
X-APIMaster-Max-Official-Price-Ratio |
Maximum ratio to official prices. Use a positive number. 0.5 allows up to half the official price and 1 allows up to the full official price. |
X-APIMaster-Max-Retries |
Maximum additional upstream attempts after the first. Use a non-negative integer. 0 allows one attempt in total. Provider switches and official-provider fallbacks count. |
X-APIMaster-Timeout-Ms |
Overall deadline in milliseconds as a positive integer, measured from gateway receipt and including routing, retries, and streaming. A shorter platform limit takes precedence. |
Use each header independently. Omitted settings follow the existing policy, and console provider preferences still apply. The price ceiling applies to input, output, and applicable cache unit rates. Total charges depend on usage. Once generation output begins streaming, the gateway does not restart it on another provider.
Supported endpoints
POST /v1/chat/completionsPOST /v1/responsesPOST /v1/messagesPOST /v1beta/models/{model}:generateContentPOST /v1beta/models/{model}:streamGenerateContent
These controls apply to text generation. Image, video, and other unsupported endpoints return 400 routing_controls_unsupported when these headers are present. Separately billed items such as tool calls are outside the text price ceiling.
Example
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."}]}'
Errors
Invalid values return 400 invalid_routing_parameter. An unavailable official baseline returns 400 official_price_unavailable. If no provider meets the price ceiling, the gateway returns 503 no_provider_within_price_limit before dispatch. A deadline returns 504 request_deadline_exceeded before a response starts or ends a stream already in progress.
