> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 모델 자동 라우팅(LLM Router)

> AIHubMix 자동 라우팅: 모델명을 auto로 지정하면 게이트웨이가 요청 내용에 따라 최적 모델을 자동 선택하며, 비용 우선 / 품질 우선 / 저지연 정책을 지원하고, 실제로 사용된 모델 기준으로 과금하며, 클라이언트 코드 변경이 전혀 필요 없습니다.

> 단 하나의 `model=auto`로 "어떤 모델을 쓸지"를 게이트웨이에 맡깁니다.

**자동 라우팅(LLM Router)** 은 요청 내용에 따라 **플랫폼의 수백 개 모델**중에서 가장 적합한 모델을 **실시간으로 선별**합니다. `model` 을 `auto` 로 지정하기만 하면 됩니다 — 모델을 고를 필요도, 가격을 비교할 필요도, 모델 업데이트를 추적할 필요도 없습니다.

<Note>
  **실제로 사용된 모델** 기준으로 과금하며, 추가 비용이 없고, 클라이언트 코드 변경이 전혀 필요 없습니다. 어떤 모델이 선택되었는지는 응답 헤더와 응답 본문에 기록되므로(자세히 보기: [실제로 사용된 모델을 확인하는 방법](#실제로-사용된-모델을-확인하는-방법)) 완전히 추적 가능합니다.
</Note>

## 적용 시나리오

* **문맥에 따른 자동 분배**: 사용자의 현재 문맥에 따라 가장 적합한 모델을 자동으로 배정합니다 — 특히 모델을 여러 번 호출하면서 각 단계의 모델 선택을 미리 고정하기 어려운 agent / 앱 시나리오에 유용합니다.
* **비용 최적화**: 간단한 작업은 더 저렴하고 빠른 모델로 자동 배치되도록 합니다(`auto` 는 기본적으로 비용 우선).
* **품질 최적화**: 복잡한 요청이 더 강력한 모델로 라우팅되도록 보장합니다(`auto:quality_first`).
* **저지연 시나리오**: 멀티턴 agent 루프, 실시간 대화형 채팅 등 응답 속도에 민감한 시나리오에서는 가장 빠르게 응답하는 모델을 우선 선택합니다(`auto:latency_critical`).
* **통합 진입점, 모델 선정 불필요**: 서로 다른 유형의 요청이 각자 최적의 모델로 자동 분배됩니다 — "작업 → 모델" 매핑 표를 유지할 필요도, 모델 업데이트를 지속적으로 추적하며 수동으로 가격을 비교하고 이름을 바꿀 필요도 없습니다.

***

## 빠른 시작

`model` 을 `auto` 로 설정하고, 나머지 요청 본문은 일반 호출과 완전히 동일하게 합니다. base\_url 은 `https://aihubmix.com/v1` 을 사용합니다.

<CodeGroup>
  ```bash curl theme={null}
  curl https://aihubmix.com/v1/chat/completions \
    -H "Authorization: Bearer <AIHUBMIX_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "auto",
      "messages": [
        { "role": "user", "content": "What is the meaning of life?" }
      ]
    }'
  ```

  ```python Python (openai SDK) theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="<AIHUBMIX_API_KEY>",
      base_url="https://aihubmix.com/v1",
  )

  resp = client.chat.completions.create(
      model="auto",  # 게이트웨이가 자동으로 모델 선택
      messages=[
          {"role": "user", "content": "What is the meaning of life?"},
      ],
  )

  print(resp.choices[0].message.content)
  print("실제로 사용된 모델:", resp.model)  # "auto" 가 아니라 실제 모델명
  ```

  ```javascript Node.js (openai SDK) theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "<AIHUBMIX_API_KEY>",
    baseURL: "https://aihubmix.com/v1",
  });

  const resp = await client.chat.completions.create({
    model: "auto", // 게이트웨이가 자동으로 모델 선택
    messages: [
      { role: "user", content: "What is the meaning of life?" },
    ],
  });

  console.log(resp.choices[0].message.content);
  console.log("실제로 사용된 모델:", resp.model); // 실제 모델명
  ```
</CodeGroup>

<Tip>
  자동 라우팅은 요청이 업스트림으로 들어가기 **전에** 분석을 완료하며, 스트리밍(`stream: true`)과 비스트리밍 요청을 동일하게 처리하고 추가 파라미터가 필요 없습니다. 전체 결정 과정은 **약 1ms 정도의 오버헤드만 추가**되어 엔드 투 엔드 지연에 거의 영향을 주지 않습니다.
</Tip>

***

## 실제로 사용된 모델을 확인하는 방법

이것은 자동 라우팅의 신뢰 기준점입니다: **이번 요청이 최종적으로 어떤 모델을 사용했는지 항상 알 수 있습니다.**

**방식 1 · AIHubMix 콘솔 '로그'**: [console.aihubmix.com/logs](https://console.aihubmix.com/logs)에서 모든 요청의 실제 적중·과금된 진짜 모델명을 코드 없이 눈으로 바로 확인할 수 있습니다.

**방식 2 · 응답 필드**(프로그래밍 방식으로 읽기에 적합):

* **응답 본문의 `model` 필드**에는 실제로 사용된 모델(예: `mimo-v2.5-pro`)이 채워지며, `auto` 가 아닙니다.
* **응답 헤더**는 완전한 결정 정보를 제공합니다:

| 응답 헤더                              | 의미                            | 예시 값                                                               |
| ---------------------------------- | ----------------------------- | ------------------------------------------------------------------ |
| `X-Aihubmix-Router-Resolved-Model` | 실제로 사용되고 그에 따라 과금되는 모델        | `xiaomi-mimo-v2.5-pro`                                             |
| `X-Aihubmix-Router-Policy`         | 이번에 사용된 정책                    | `cost_optimized`                                                   |
| `X-Aihubmix-Router-Dimension`      | 식별된 작업 차원                     | `text.overall`                                                     |
| `X-Aihubmix-Router-Decision-Id`    | 이번 결정의 고유 ID, 문제 추적에 유용       | `05dbad09-33c5-42de-…`                                             |
| `X-Aihubmix-Router-Reason`         | 결정 요약(정책 / 차원 / 최고 점수 / 후보 수) | `policy=cost_optimized dim=text.overall top=0.182 survivors=20/33` |
| `X-Aihubmix-Router-Fallback`       | **무후보 폴백이 발동된 경우에만** 나타남      | `true`                                                             |

> HTTP 응답 헤더는 대소문자를 구분하지 않습니다. 위 표는 관례상 첫 글자를 대문자로 표기했지만, 실제 HTTP/2 응답은 소문자 `x-aihubmix-router-*` 로 반환되며 둘은 동일합니다.

라우팅 결정 읽기(curl 로 응답 헤더 확인, SDK 로는 원시 응답 객체에서 header 획득):

<CodeGroup>
  ```bash curl theme={null}
  curl -i https://aihubmix.com/v1/chat/completions \
    -H "Authorization: Bearer <AIHUBMIX_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "auto",
      "messages": [
        { "role": "user", "content": "What is the meaning of life?" }
      ]
    }' | grep -i "^x-aihubmix-router"
  ```

  ```python Python (openai SDK) theme={null}
  # 위에서 생성한 client 재사용; with_raw_response 라야 응답 헤더를 얻을 수 있음
  raw = client.chat.completions.with_raw_response.create(
      model="auto",
      messages=[
          {"role": "user", "content": "What is the meaning of life?"},
      ],
  )

  print("사용된 모델:", raw.headers.get("x-aihubmix-router-resolved-model"))
  print("정책:", raw.headers.get("x-aihubmix-router-policy"))
  print("차원:", raw.headers.get("x-aihubmix-router-dimension"))

  completion = raw.parse()  # 일반적인 completion 객체로 파싱
  print("body.model:", completion.model)
  ```

  ```javascript Node.js (openai SDK) theme={null}
  // 위에서 생성한 client 재사용; .withResponse() 라야 원시 응답 헤더를 얻을 수 있음
  const { data: completion, response } = await client.chat.completions
    .create({
      model: "auto",
      messages: [
        { role: "user", content: "What is the meaning of life?" },
      ],
    })
    .withResponse();

  console.log("사용된 모델:", response.headers.get("x-aihubmix-router-resolved-model"));
  console.log("정책:", response.headers.get("x-aihubmix-router-policy"));
  console.log("차원:", response.headers.get("x-aihubmix-router-dimension"));
  console.log("body.model:", completion.model);
  ```
</CodeGroup>

curl 실제 출력(프로덕션 환경, 사용된 모델은 온라인 catalog 변화에 따라 달라짐):

```text theme={null}
x-aihubmix-router-decision-id: 05dbad09-33c5-42de-85b5-559fdb73eb4c
x-aihubmix-router-dimension: text.overall
x-aihubmix-router-policy: cost_optimized
x-aihubmix-router-reason: policy=cost_optimized dim=text.overall top=0.182 survivors=20/33
x-aihubmix-router-resolved-model: xiaomi-mimo-v2.5-pro
```

`reason` 읽는 법: `survivors=20/33` 은 33개 후보 중 20개가 하드 필터를 통과해 점수 산정에 진입했음을 의미하고, `top=0.182` 는 승리한 모델이 후보 풀 내에서 정규화된 종합 점수입니다(능력 / 비용 / 지연을 정책에 따라 가중).

<Note>
  예시의 `Resolved-Model` 은 온라인 catalog 의 현재 후보와 가격에 따라 달라지며, 플랫폼 모델의 출시 / 종료에 따라 변합니다 — 이것이 바로 자동 라우팅의 가치입니다: 이러한 변화를 추적할 필요가 없습니다. 결정을 복기 가능하게 하려면, 고정되어 있다고 가정하지 말고 응답 헤더 / 응답 본문의 실제 모델명을 기준으로 삼으세요.
</Note>

***

## 라우팅 정책

접미사 없는 `auto` 는 기본 정책 `cost_optimized` 를 사용합니다. `auto:<정책>` 으로 중점을 명시적으로 지정할 수 있습니다:

| 정책 표기                           | 중점                                  | 적용 시나리오              |
| ------------------------------- | ----------------------------------- | -------------------- |
| `auto`(= `auto:cost_optimized`) | **비용 우선**: 능력이 기준을 충족하면 가장 저렴한 것 선택 | 배치 작업, 비용에 민감한 경우    |
| `auto:balanced`                 | **균형**: 능력 / 비용 / 지연을 두루 고려         | 범용, 확신이 없을 때의 안전한 선택 |
| `auto:quality_first`            | **품질 우선**: 능력이 가장 강한 것 우선 선택        | 복잡한 추론, 핵심 출력        |
| `auto:latency_critical`         | **저지연 우선**: 응답이 가장 빠른 것 우선 선택       | agent 루프, 실시간 대화형 채팅 |

전략은 고정된 '모델 목록' 이 아니라 **능력 / 비용 / 지연** 에 대한 서로 다른 가중치 지향입니다. `auto` 는 먼저 이번 요청의 내용으로 작업 차원을 좁힌 뒤, 해당 차원에서 **플랫폼의 수백 개 모델** 후보 풀 중 선택한 전략에 따라 실시간으로 최적을 고릅니다 — 따라서 같은 전략이라도 내용에 따라 서로 다른 모델에 적중합니다. 현재 풀 내 모델과 각 차원별 점수는 [자동 라우팅 전략 대상 모델 범위](/ko/api/RouterEndpoints/leaderboard) 엔드포인트로 조회할 수 있습니다. 아래 '같은 요청, 다른 전략 → 다른 적중' 실측 표가 바로 이 메커니즘을 직관적으로 보여줍니다. 매번 어떤 모델이 선택되는지는 응답 헤더 / 콘솔 로그의 실제 모델명을 기준으로 합니다.

정책을 지정하려면 `model` 에 접미사를 붙이기만 하면 됩니다:

<CodeGroup>
  ```bash curl theme={null}
  # 품질 우선 + 코드 작업
  curl -i https://aihubmix.com/v1/chat/completions \
    -H "Authorization: Bearer <AIHUBMIX_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "auto:quality_first",
      "messages": [
        { "role": "user", "content": "Write a Python function to reverse a linked list." }
      ]
    }' | grep -i "^x-aihubmix-router"
  ```

  ```python Python (openai SDK) theme={null}
  raw = client.chat.completions.with_raw_response.create(
      model="auto:quality_first",  # 품질 우선
      messages=[
          {"role": "user", "content": "Write a Python function to reverse a linked list."},
      ],
  )

  print(raw.headers.get("x-aihubmix-router-resolved-model"))
  print(raw.headers.get("x-aihubmix-router-dimension"))
  ```

  ```javascript Node.js (openai SDK) theme={null}
  const { response } = await client.chat.completions
    .create({
      model: "auto:quality_first", // 품질 우선
      messages: [
        { role: "user", content: "Write a Python function to reverse a linked list." },
      ],
    })
    .withResponse();

  console.log(response.headers.get("x-aihubmix-router-resolved-model"));
  console.log(response.headers.get("x-aihubmix-router-dimension"));
  ```
</CodeGroup>

**동일한 요청, 다른 정책 → 다른 선택 결과**(프로덕션 실측, 동일한 문장 `What is the meaning of life?`, 모두 `text.overall` 차원으로 분류):

| 정책                         | 사용된 모델                  | top 점수 |
| -------------------------- | ----------------------- | :----: |
| `auto`(= `cost_optimized`) | `xiaomi-mimo-v2.5-pro`  |  0.182 |
| `auto:balanced`            | `claude-opus-4-6-think` |  0.488 |
| `auto:latency_critical`    | `claude-opus-4-6`       |  0.646 |
| `auto:quality_first`       | `claude-opus-4-6-think` |  0.758 |

> `latency_critical` 은 **`-think` 가 아닌 버전**을 선택했습니다 — thinking 변형은 추론 지연이 더 높아, 저지연 정책은 이를 능동적으로 회피합니다. 정책 가중치가 단지 능력만 보는 것이 아니라 "능력 / 비용 / 지연" 의 절충에 실제로 작용함을 알 수 있습니다.

> **내용 또한 결과를 바꿉니다**: 동일한 `auto:quality_first` 를 **코드 작업**에 적용하면(위 예시의 요청), 차원이 `text.overall` 에서 `text.coding` 으로 바뀌고 실측 결과 `claude-opus-4-6-think` 가 선택됩니다 — 정책과 요청 내용이 함께 최종 모델을 결정합니다.

<Note>
  알 수 없는 정책 접미사(예: `auto:fast`)는 **기본 정책 `cost_optimized` 로 폴백**되며, 오류를 반환하지 않습니다.
</Note>

***

## 작동 원리

`model=auto` 를 받으면, 게이트웨이는 세 단계로 "의도" 를 "구체적인 모델" 로 변환합니다:

<Steps>
  <Step title="요청 특징 추출">
    이번 요청의 입력 / 출력 모달리티(텍스트, 이미지, 파일), 내용 의도(코드, 수학, OCR, 차트, 언어, 웹 검색 여부 등), 그리고 요청 규모(예상 입력 / 출력 token)를 분석하여 하나의 **작업 차원**으로 정규화합니다. 예: 코드가 포함된 질문 → `text.coding`; 이미지를 포함하고 OCR 요구 → `vision.ocr`; 일반 텍스트 → `text.overall`.
  </Step>

  <Step title="후보 하드 필터링">
    **하드 제약**을 충족하지 못하는 모델을 즉시 제외합니다: 필요한 입력 / 출력 모달리티를 지원하지 않거나, 컨텍스트 윈도우에 담을 수 없거나, 서킷 브레이커로 제외되었거나(자세히 보기: [안정성과 장애 대응](#안정성과-장애-대응)), 해당 Key 로 사용 가능한 모델 범위에 없는 경우.
  </Step>

  <Step title="정책에 따른 가중 점수 산정">
    필터를 통과한 후보에 대해, **업계 권위 있는 벤치마크** 기반의 모델 능력 점수에 실시간 가격 및 성능 데이터를 더해, 선택한 정책에 따라 "능력 / 비용 / 지연" 을 3차원 가중 점수로 산정하고 가장 높은 점수의 하나를 선택합니다. 최종 모델명은 요청과 응답 헤더에 다시 기록됩니다.
  </Step>
</Steps>

실제 점수 산정 예시(`quality_first` 전략에서 동일 후보 풀의 top 3, 예시 데이터는 과거 프로덕션 의사결정 로그 기반):

| 후보 모델                   | 능력 점수 | 상대 비용 |    지연   |   종합 점수   |
| ----------------------- | :---: | :---: | :-----: | :-------: |
| `claude-opus-4-6-think` |  1504 |  220  |  1963ms | **0.758** |
| `claude-opus-4-6`       |  1498 |  220  |  822ms  |   0.721   |
| `claude-fable-5`        |  1510 |  484  | 11130ms |   0.600   |

> `claude-fable-5` 의 **능력 점수가 가장 높음**(1510)에도 불구하고, 비용이 더 높고 지연이 더 커서 종합 점수가 3위로 밀린 점에 주목하세요. 이것이 바로 가중 점수 산정의 의미입니다: "능력 지상주의" 가 아니라, 정책에 따라 능력 / 비용 / 지연 사이에서 절충합니다.

<Note>
  `claude-fable-5` 는 단계적으로 공개된 프리뷰 베이스라인 모델(staged preview baseline)로, 현재 **지원 종료(deprecated)** 되어 더 이상 제공되지 않습니다. 여기서는 가중 점수 산정 메커니즘을 설명하기 위해 과거 점수만 남겨두었으며, 실제 요청은 더 이상 이 모델에 적중하지 않습니다.
</Note>

차원 식별은 자동입니다 — 자동 라우팅은 **30개 이상의 세분화된 작업 차원**(코드 / 수학 / OCR / 차트 / 장문 / 중국어 / 웹 검색…)을 내장하고 있어, "모델 계열별 거친 분배" 보다 훨씬 정밀합니다. 동일하게 `auto` 로 지정해도, 내용이 다르면 다른 차원으로 라우팅됩니다:

| 당신의 요청                                      | 식별된 차원                    |
| ------------------------------------------- | ------------------------- |
| 일반 텍스트 질문                                   | `text.overall`            |
| 코드 포함, 프로그램 작성 / 디버깅 요구                     | `text.coding`             |
| 수학 증명 / 풀이                                  | `text.math`               |
| 매우 긴 질문(약 500+ token)                       | `text.longer_query`       |
| 중국어 질문                                      | `text.language.chinese`   |
| 이미지 입력 + "What is in this image?"           | `vision.overall`          |
| 이미지 입력 + "OCR…" / "글자 인식"                   | `vision.ocr`              |
| 이미지 입력 + 차트 / 플로차트                          | `vision.diagram`          |
| 웹 검색 활성화                                    | `search.overall`          |
| 이미지 생성(`/v1/images/generations`)            | `text_to_image.overall`   |
| 이미지 편집(`/v1/images/edits`, 이미지 입력 → 이미지 출력) | `image_edit.single_image` |

이 차원 이름들은 모델의 **세분화된 능력** 을 분해한 업계 권위 평가 리더보드에서 유래하며, `auto` 는 이에 따라 각 유형의 요청을 해당 세부 능력이 가장 강한 모델로 보냅니다. 흔한 영역 예시:

* **텍스트**: `text.coding` = 코드 작성 / 디버깅, `text.math` = 수학 풀이, `text.longer_query` = 장문 처리, `text.language.chinese` = 중국어, `text.occupational.legal` / `text.occupational.medicine` = 법률 / 의료 등 직업 시나리오.
* **비전**: `vision.ocr` = 이미지 속 텍스트 인식, `vision.diagram` = 차트 / 플로차트 이해, `vision.overall` = 일반 이미지 이해.

<Tip>
  차원 식별은 보수적 매칭(높은 정밀도, 낮은 오판)을 채택합니다: 롱테일이거나 모호한 요청은 억지로 분류되지 않고 더 범용적인 차원(예: `text.overall` / `vision.overall`)으로 분류되어, 오라우팅을 방지합니다.
</Tip>

<Note>
  **이미지 입력 또한 자동 라우팅을 거칩니다**: `/v1/chat/completions` 에 이미지를 포함할 때, 이미지 작업에 따라 비전 능력이 강한 모델로 라우팅됩니다. 프로덕션 실측 — 「OCR this image」→ `vision.ocr`, `qwen3.5-397b-a17b` 선택; 일반 이미지 보기 「What is in this image?」→ `vision.overall`, `gpt-5.4-mini` 선택. (여기서는 이미지 **이해**를 가리킵니다; 이미지 **생성** `/v1/images/*` 도 `auto` 를 지원합니다, [FAQ](#자주-묻는-질문-faq) 참고.)
</Note>

***

## 점수 리더보드 및 모델 풀

차원별 모델 점수 리더보드와 현재 모델 풀은 [LLM Router 페이지](https://aihubmix.com/llm-router/auto?lang=en)에서 인터랙티브하게 볼 수 있으며, 로그인 없는 오픈 엔드포인트([자동 라우팅 전략 대상 모델 범위](/ko/api/RouterEndpoints/leaderboard), [모델 벤더 아이콘](/ko/api/RouterEndpoints/vendors))로 직접 조회할 수도 있습니다. 리더보드 표시 기준은 라우팅 후보와 동일합니다. 현재 정상적으로 라우팅 가능한 모델만 표시되고, 점수는 각 차원 내에서 0–100으로 정규화되며, 모델 풀에 따라 지속적으로 갱신됩니다.

***

## 안정성과 장애 대응

자동 라우팅은 **다중 장애 대응**을 내장하여 `auto` 경로가 **이유 없이 실패하지 않도록** 보장합니다:

<AccordionGroup>
  <Accordion title="서킷 브레이커: 장애 모델 자동 제외">
    게이트웨이는 각 모델에 대해 슬라이딩 윈도우 기반의 실패율 통계를 유지합니다. 어떤 모델이 윈도우 내에서 실패 횟수가 충분히 많고 실패율이 임계값을 초과하면, 일시적으로 후보 풀에서 제외되며 일정 시간 쿨다운 후 자동 복구됩니다 — 후속 요청을 계속 오작동 중인 모델로 보내는 것을 방지합니다. 실패 신호는 **업스트림이 해당 요청에 반환한 오류**에서 나옵니다; 게이트웨이 자체의 "사용 가능한 채널 없음" 은 집계되지 않습니다(그것은 모델 자체의 문제가 아니기 때문).
  </Accordion>

  <Accordion title="무후보 폴백: auto 에서 절대 400 을 반환하지 않음">
    만에 하나 하드 필터가 모든 후보를 제외했더라도(예: 특정 모달리티 조합에 사용 가능한 모델이 일시적으로 없는 경우), 게이트웨이는 직접 오류를 반환하지 않고 출력 유형에 따라 폴백 모델을 할당하여 응답을 보장하며, 응답 헤더에 `X-Aihubmix-Router-Fallback: true` 를 추가하여 알려줍니다.
  </Accordion>

  <Accordion title="권한 방어선: 제한된 Key 는 폴백으로도 우회되지 않음">
    Key 가 사용 가능한 모델 범위를 한정한 경우, 자동 라우팅(폴백 포함)이 선택하는 모델은 **항상** 그 범위 내에 있습니다. 범위 내에 이번 요청을 처리할 수 있는 모델이 정말 하나도 없다면, 범위 밖의(잠재적으로 더 비싼) 모델을 조용히 사용하지 않고 명시적으로 403 을 반환합니다.
  </Accordion>
</AccordionGroup>

***

## 과금 안내

**실제로 사용된 모델의 정가 기준으로 과금하며, 자동 라우팅 자체는 어떤 추가 비용도 받지 않습니다.**

최종적으로 어떤 모델이 응답하든, 그 모델의 가격, 능력, 컨텍스트 제한에 따라 계산됩니다 — 이 모델은 바로 응답 헤더 `X-Aihubmix-Router-Resolved-Model` 과 응답 본문 `model` 필드의 값입니다. 다시 말해, 자동 라우팅은 "몰래 비싼 모델을 쓰지" 않습니다: 매번 선택된 모델은 응답에 기록되어 건별로 대조 확인할 수 있습니다.

***

## 제한 사항

* 자동 라우팅은 현재 **대화 완성** `/v1/chat/completions` 및 **이미지 생성 / 편집** `/v1/images/*` 인터페이스를 대상으로 합니다(자세히 보기: [FAQ: 어떤 인터페이스를 지원하나요](#자주-묻는-질문-faq)).

* `?router=off` 또는 요청 헤더 `X-Router-Off` 는 `model=auto` 가 곧바로 **400** 을 반환하게 합니다 — 이는 "auto 를 쓰면서 라우팅을 끄려는" 모호한 사용법을 명확히 거부하는 것이며, 조용히 무시하는 것이 아닙니다:

  ```bash theme={null}
  curl -i "https://aihubmix.com/v1/chat/completions?router=off" \
    -H "Authorization: Bearer <AIHUBMIX_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}'
  # → HTTP/1.1 400 Bad Request
  # {"error":{"message":"auto requires router enabled; remove ?router=off / X-Router-Off", ...}}
  ```

* 후보 집합은 플랫폼 catalog 에 따라 동적으로 변합니다: 동일한 `auto` 라도 시점이 다르면 다른 모델이 선택될 수 있습니다(이는 설계상 의도된 것으로, 응답 헤더로 복기 가능). 현재 후보 범위는 [자동 라우팅 전략 대상 모델 범위](/ko/api/RouterEndpoints/leaderboard) 엔드포인트로 조회할 수 있습니다.

***

## OpenRouter / LiteLLM 과의 차이점

"자동 모델 선택" 은 AIHubMix 만의 고유 기능이 아닙니다. OpenRouter 와 LiteLLM 도 유사한 기능을 제공합니다. 차이는 주로 **도입 비용**과 **호스팅 방식**에 있습니다:

| 차이점                                                | OpenRouter | LiteLLM | AIHubMix |
| -------------------------------------------------- | :--------: | :-----: | :------: |
| 요청 내용에 따른 자동 모델 선택                                 |      ✅     |    ✅    |     ✅    |
| 무설정, 즉시 사용 가능(라우팅 규칙 / utterances 작성 불필요)          |      ✅     |    ❌    |     ✅    |
| 플랫폼 호스팅, 자체 구축 / 자체 배포 proxy 불필요                   |      ✅     |    ❌    |     ✅    |
| 비용 / 품질 / 지연 다중 정책, 파라미터 하나로 전환                    |      ❌     |    ❌    |     ✅    |
| 선택 결정 추적 가능(응답 헤더에 dimension / policy / reason 포함) |      ❌     |    ❌    |     ✅    |
| 최종 사용된 모델 기준 과금                                    |      ✅     |    ❌    |     ✅    |

***

## 자주 묻는 질문 FAQ

**Q: 자동 라우팅은 어떤 인터페이스를 지원하나요?**
A: 현재 `model=auto` 는 **OpenAI 호환 대화 완성 인터페이스** `/v1/chat/completions` 와 **이미지 생성 / 편집 인터페이스**(`/v1/images/generations`, `/v1/images/edits`)를 지원합니다. 오디오, `/v1/embeddings`, `/v1/rerank` 등의 인터페이스는 현재 `auto` 를 지원하지 않으므로 구체적인 모델을 직접 지정하세요.

**Q: 자동 라우팅은 이미지 입력을 지원하나요?**
A: 지원합니다. `/v1/chat/completions` 에 이미지(`image_url`)를 포함하여 질문하는 것은 이미지 **이해**에 속하며, 이미지 작업에 따라 비전 능력이 강한 모델로 라우팅됩니다(이미지 속 텍스트 인식 `vision.ocr`, 차트 / 플로차트 이해 `vision.diagram`, 일반 이미지 이해 `vision.overall` 등). 이미지 **생성**도 `auto` 를 지원합니다. `/v1/images/*` 인터페이스에서 `model` 을 `auto` 로 지정하면 이미지 생성 차원(예: `text_to_image.overall`)에 따라 모델이 선택됩니다.

**Q: 이번 요청이 도대체 어떤 모델을 사용했는지 어떻게 알 수 있나요?**
A: 응답 헤더 `X-Aihubmix-Router-Resolved-Model`, 또는 응답 본문의 `model` 필드를 보세요 — 둘 다 실제 모델명이 채워집니다. 자세히 보기: [실제로 사용된 모델을 확인하는 방법](#실제로-사용된-모델을-확인하는-방법).

**Q: 자동 라우팅이 몰래 비싼 모델을 쓰지는 않나요?**
A: 그렇지 않습니다. 기본 정책 `cost_optimized` 는 비용 우선이며, 게다가 매번 선택된 모델은 응답에 기록되어 그 정가 기준으로 과금되므로 건별로 대조 확인할 수 있습니다. 자세히 보기: [과금 안내](#과금-안내).

**Q: 비용을 어떻게 제어 / 예측하나요?**
A: 세 가지 수단을 함께 사용합니다 — ① 기본 `auto`(`cost_optimized`)가 곧 비용 우선; ② **Key 의 사용 가능 모델 범위**로 후보를 수용 가능한 가격대 내로 한정하여 비용 상한을 두는 효과; ③ 매번 선택된 모델은 응답 헤더 `Resolved-Model` 모델의 정가 기준으로 과금되어 건별로 대조 확인 가능. 더 강한 능력이 필요할 때 명시적으로 `auto:quality_first` 를 사용하세요.

**Q: `auto` 와 「모델 매핑 / 폴백」의 차이는 무엇인가요?**
A: [모델 매핑 / 폴백](https://docs.aihubmix.com/ko/api/Model-Mapping-Fallback)은 **Key 단위 고정 별칭 + 실패 시 순서가 있는 폴백**(매번 동일한 대상)이고, 자동 라우팅은 **매 요청 내용에 따른 동적 모델 선택**입니다. 전자는 "클라이언트가 특정 이름만 인식 / 주 모델이 다운되면 예비로 전환" 을 해결하고, 후자는 "어느 것이든 상관없으니 가장 적합한 것을 달라" 를 해결합니다.

**Q: 자동 라우팅이 특정 몇 개 모델 안에서만 선택하도록 한정할 수 있나요?**
A: 가능합니다 — **Key 의 사용 가능 모델 범위**로 제약하면 됩니다: 자동 라우팅은 그 Key 가 허용한 모델 안에서만 선택하며, 범위 밖 모델은 선택되지 않습니다.

**Q: 스트리밍 요청을 지원하나요?**
A: 지원합니다. 라우팅은 요청이 업스트림으로 들어가기 전에 완료되며, 스트리밍 / 비스트리밍을 동일하게 처리합니다.

**Q: 왜 같은 문장을 두 번 호출했는데 다른 모델이 선택되었나요?**
A: 후보 집합과 가격이 플랫폼 catalog 에 따라 동적으로 변하기 때문이며, 이는 설계상 의도된 것입니다. 응답 헤더의 `Decision-Id` 와 `Resolved-Model` 로 매 결정을 복기할 수 있습니다. 현재 후보 범위는 [자동 라우팅 전략 대상 모델 범위](/ko/api/RouterEndpoints/leaderboard) 엔드포인트로 조회할 수 있습니다.

**Q: 요청이 안정적으로 동일한 모델을 선택하게 하려면 어떻게 하나요(예: prompt 캐시를 재사용하고 싶을 때)?**
A: `auto` 는 현재 catalog 에 따라 동적으로 모델을 선택하므로 결정론적이지 않습니다. 안정적으로 동일한 모델을 선택해야 한다면(예: 업스트림의 prompt 캐시에 의존하거나, 엄격한 재현이 필요한 경우), **구체적인 모델명을 직접 지정**하거나 **Key 로 사용 가능 범위를 단일 모델로 한정**하세요 — 이 두 방식에서는 선택이 결정론적입니다.

***

## 관련 리소스

* [모델 매핑과 폴백](https://docs.aihubmix.com/ko/api/Model-Mapping-Fallback): Key 단위 고정 별칭 + 실패 폴백, 자동 라우팅과 상호 보완적입니다.
* [통합 추론 파라미터](https://docs.aihubmix.com/ko/api/unified-inference): 모델 전반에 걸쳐 일관된 요청 파라미터.
* [AIHubMix 모델 페이지](https://aihubmix.com/models): 모델 이름, 가격 및 `Input Modalities` 조회.
* [자동 라우팅 전략 대상 모델 범위](https://docs.aihubmix.com/ko/api/RouterEndpoints/leaderboard): 30+ 라우팅 차원 중 공개된 5개 대분류 23개 하위 차원 점수와 풀 내 모델을 로그인 없이 조회할 수 있습니다.