엔드포인트

제공자 라우팅과 폴백

provider 객체의 order, only, ignore, sort, max_price 등으로 업스트림 제공자를 고르고 거르는 방법과 models 배열로 제공자 및 모델 간 폴백을 구성하는 방법을 요청 예제와 오류와 함께 설명합니다.

플레이그라운드에서 사용해 보기

많은 모델이 여러 업스트림 제공자에서 제공되며, 제공자마다 가격, 속도, 데이터 정책이 다릅니다. 기본적으로 요청은 가격과 가동 시간을 기준으로 제공자 간에 부하가 분산되고, 한 제공자가 실패하면 다른 제공자로 폴백합니다. 이를 바꾸려면 provider 객체를, 서로 다른 모델 간에 폴백하려면 models를 사용하세요.

`provider` 객체

필드	타입	설명
`order`	string[]	먼저 시도할 제공자를 순서대로 지정합니다. 예: `["Anthropic", "Amazon Bedrock"]`.
`allow_fallbacks`	boolean	`false`이면 `order` 또는 `only` 밖의 제공자로 요청이 가지 않습니다(기본값 `true`).
`only`	string[]	이 제공자만 허용합니다.
`ignore`	string[]	이 제공자는 절대 사용하지 않습니다.
`sort`	string	부하 분산 대신 `"price"`, `"throughput"`, `"latency"`로 정렬합니다.
`data_collection`	string	`"deny"`는 프롬프트를 저장하거나 학습에 사용할 수 있는 제공자를 제외합니다. 기본값은 `"allow"`입니다.
`require_parameters`	boolean	요청의 모든 파라미터(예: `tools`, `response_format`)를 지원하는 제공자만 사용합니다.
`quantizations`	string[]	허용하는 정밀도. 예: `["fp8", "bf16"]`.
`max_price`	object	100만 토큰당 USD 기준 가격 상한. 예: `{ "prompt": 1, "completion": 3 }`.

{
  "model": "meta-llama/llama-3.3-70b-instruct",
  "messages": [{ "role": "user", "content": "Hello" }],
  "provider": {
    "order": ["Groq", "Fireworks"],
    "allow_fallbacks": true,
    "data_collection": "deny",
    "sort": "throughput"
  }
}

:nitro 변형은 sort: "throughput"의 단축 표기이고, :floor는 sort: "price"의 단축 표기입니다. 모델 ID를 참고하세요.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api14.com/api/v1",
  apiKey: process.env.API14_API_KEY,
});

const result = await client.chat.completions.create({
  "model": "openai/gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "Explain vector databases in two sentences."
    }
  ]
});
console.log(result.choices[0].message.content);

`models`를 이용한 모델 폴백

모델 목록을 전달하세요. 첫 번째 모델이 실패하면(장애, 속도 제한, 모더레이션, 컨텍스트 길이 오류) 다음 모델을 시도합니다.

{
  "models": ["anthropic/claude-sonnet-4.5", "openai/gpt-5-mini", "google/gemini-2.5-flash"],
  "messages": [{ "role": "user", "content": "Summarize this ticket." }]
}

models를 설정하면 model은 선택 사항입니다. 둘 다 보내면 model을 먼저 시도합니다.
목록의 모든 모델은 요청이 전송되기 전에 게이트웨이 검사를 통과해야 합니다. 모델이 존재하고 활성화되어 있어야 하며, 키의 모델 허용 목록에 있어야 하고, 요금제에 포함되어야 합니다. 검사에 실패하는 모델이 하나라도 있으면 요청 전체가 거부됩니다(403 model_not_allowed, 403 plan_required, 404 model_not_found).
응답한 모델에 대해서만 해당 모델의 가격으로 과금됩니다. 응답의 model 필드로 어느 모델이었는지 알 수 있습니다.

응답

{
  "id": "gen-1760000000-route",
  "model": "openai/gpt-5-mini",
  "provider": "OpenAI",
  "choices": [{ "index": 0, "finish_reason": "stop", "message": { "role": "assistant", "content": "..." } }],
  "usage": { "prompt_tokens": 140, "completion_tokens": 60, "total_tokens": 200, "cost": 0.000155 }
}

provider는 요청을 처리한 업스트림 제공자를 보여 줍니다. 생성 조회에서는 라우팅 세부 정보를 모두 볼 수 있습니다.

오류

필터와 일치하는 제공자가 없으면(예: only와 require_parameters를 함께 사용한 경우) 업스트림이 "No endpoints found"와 함께 404를 반환합니다. 그 밖의 오류는 Chat completions와 같습니다. 오류를 참고하세요.

제공자 라우팅과 폴백

provider 객체

models를 이용한 모델 폴백

응답

오류

`provider` 객체

`models`를 이용한 모델 폴백