APIMaster.ai

요청별 라우팅 제어

선택적 HTTP 헤더로 텍스트 생성의 공식 가격 대비 상한, 재시도 횟수, 전체 제한 시간을 설정합니다.

요청별 라우팅 제어

채널 포함 또는 제외

텍스트, 이미지 또는 동영상 생성 요청의 채널 범위를 지정합니다. 두 헤더를 함께 사용할 수 있으며 제외가 우선됩니다.

  • X-APIMaster-Include-Channels · 나열된 채널만 허용합니다.
  • X-APIMaster-Exclude-Channels · 나열된 채널을 제외합니다.

각 헤더는 쉼표로 구분한 양의 정수를 최대 64개 받습니다. 모델의 공개 channel_id를 조회하세요. API 키와 콘솔 설정이 사용 가능한 채널을 결정합니다. 채널은 요청의 작업과 매개변수도 지원해야 합니다.

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를 반환하고, 진행 중인 스트림은 종료합니다.