APIMaster.ai

Controles de roteamento por requisição

Defina um limite em relação ao preço oficial, novas tentativas e um prazo total para a geração de texto usando cabeçalhos HTTP opcionais.

Controles de roteamento por requisição

Incluir ou excluir canais

Defina o conjunto de canais de uma solicitação de texto, imagem ou vídeo. Os dois cabeçalhos podem ser usados juntos. Exclusões têm prioridade.

  • X-APIMaster-Include-Channels · Permite apenas os canais listados.
  • X-APIMaster-Exclude-Channels · Exclui os canais listados.

Cada cabeçalho aceita até 64 inteiros positivos separados por vírgulas. Consulte os valores públicos de channel_id do modelo. A chave de API e as preferências do console determinam quais canais estão disponíveis. O canal também precisa aceitar a operação e os parâmetros da solicitação.

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

Tentativas e rotas alternativas respeitam esse conjunto. A geração assíncrona o preserva, e os endpoints idempotentes o incluem na verificação.

Cabeçalhos inválidos retornam 400 invalid_routing_parameter. Sem um canal elegível, a API retorna 503 no_provider_within_channel_scope. Consultas e downloads usam o canal da tarefa existente.

Omita os cabeçalhos ao consultar ou baixar um resultado. Endpoints incompatíveis e o pool gerenciado FreeModel retornam 400 routing_controls_unsupported.

Exemplos de geração

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"}'

Preço, tentativas e prazo para texto

Defina um limite em relação ao preço oficial, novas tentativas e um prazo total para a geração de texto usando cabeçalhos HTTP opcionais.

Cabeçalho Comportamento
X-APIMaster-Max-Official-Price-Ratio Proporção máxima do preço oficial como número positivo. 0.5 aceita até metade do preço oficial e 1 aceita até o preço oficial integral.
X-APIMaster-Max-Retries Número máximo de tentativas adicionais após a primeira, como inteiro não negativo. 0 permite uma única tentativa. Trocas de provedor e o uso do provedor oficial como alternativa contam.
X-APIMaster-Timeout-Ms Prazo total em milissegundos, como inteiro positivo a partir do recebimento no gateway. Inclui roteamento, novas tentativas e streaming. Prevalece o menor prazo.

Cada cabeçalho é independente. As opções omitidas seguem a política atual, e as preferências de provedor do console continuam válidas. O teto se aplica aos preços unitários de entrada, saída e cache aplicável. O custo total depende do uso. Após o início do envio de conteúdo, o gateway não reinicia a geração em outro provedor.

Endpoints compatíveis

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

Esses controles se aplicam à geração de texto. Endpoints de imagem, vídeo e outros não compatíveis retornam 400 routing_controls_unsupported se receberem esses cabeçalhos. Itens cobrados separadamente, como chamadas de ferramentas, ficam fora do teto de texto.

Exemplo

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."}]}'

Erros

Valores inválidos retornam 400 invalid_routing_parameter. Sem preço oficial verificável, a API retorna 400 official_price_unavailable. Sem provedor dentro do limite, retorna 503 no_provider_within_price_limit antes do envio. Ao vencer o prazo, retorna 504 request_deadline_exceeded antes do início da resposta ou encerra o streaming em andamento.