> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 그룹이란 무엇인가? 사용자 그룹 vs 토큰 그룹 설명
> APIYI의 그룹 개념을 깊이 있게 살펴봅니다. 사용자 입장에서는 '내 그룹'처럼 느껴지지만, 실제로 모든 호출에 적용되는 것은 토큰에 선택된 그룹입니다. ClaudeCode, Sora2Official, Wan&HappyHorse 전용 그룹 사례와 '상위 그룹이 포화되었습니다' 429 오류를 분석한 실제 티켓도 포함합니다.
## 한 문장으로
**그룹은 token에 선택하는 “호출 채널”입니다. 사용 가능한 모델, 과금 요율 배수, 업스트림 라우팅을 결정합니다.** 사용자 입장에서는 “나만의 그룹”처럼 느껴지지만, **모든 개별 호출에서 실제로 적용되는 것은 token에 선택된 그룹입니다**.
## 사용자 관점 vs 플랫폼 관점
그룹은 토큰을 생성하거나 편집할 때 제가 **선택하는 채널**입니다. 이 그룹은 이 토큰이 호출할 수 있는 모델, 적용되는 배수, 그리고 어떤 업스트림 경로를 타는지를 결정합니다.
그룹은 **리소스 관리와 기능 노출**을 위한 도구입니다. 유사한 모델, 전용 용량, 대상별 할인을 하나의 채널로 묶어 과금은 정확하게 유지하고 가격은 차별화할 수 있게 합니다.
## "사용자 그룹" ≠ "token 그룹" — 혼동하지 마십시오
흔히 처음 드는 반응은 다음과 같습니다. “내 계정에 어딘가에서 전환해야 하는 그룹이 있습니까?”
* 계정 수준에는 "사용자 그룹" 개념이 있으며, 이는 **기본 권한 범위**를 결정합니다(SVIP 모델이 표시되는지, 엔터프라이즈 대체 그룹이 잠금 해제되는지 등)
* 하지만 **모든 API 호출의 라우팅, 요율 배수, 모델 사용 가능 여부는 token에서 선택한 그룹이 결정합니다**.
문제를 해결할 때는 먼저 token의 “그룹 선택”과 “대체 그룹” 설정을 확인하십시오 — “내 계정의 그룹”을 찾아 헤매지 마십시오. [Tokens & Groups](/ko/faq/token-and-groups)를 참조하십시오.
## 사례 1: `ClaudeCode` 그룹은 왜 존재합니까?
**목적**: Anthropic 네이티브 `/v1/messages` 호출 형식을 지원하는 모델을 하나의 채널로 묶어, Claude Code, Cherry Studio 및 기타 Anthropic 네이티브 클라이언트 안에서 국내 코딩 모델을 Claude를 호출하는 것처럼 사용할 수 있게 하며, 코드 변경은 필요 없습니다.
**포함 모델**:
* 전체 Claude 라인업(공식 릴레이 / AWS Claude)
* `/v1/messages`와 호환되는 국내 모델, 예: `qwen3.x-max`, `glm-5.x`, `deepseek-v4`
**할인**:
* 기본 **5% 할인(95 折)** — 별도 조치가 필요 없습니다
* **충전 보너스(10%–20%)와 중복 적용**되므로, 실제 비용은 공식 직접 구매보다 약 20% 낮아집니다
**사용 방법**:
1. [https://api.apiyi.com/token](https://api.apiyi.com/token)을 열고 token을 생성하거나 수정합니다
2. "그룹 선택"을 `ClaudeCode`로 설정합니다
3. 클라이언트에서 Anthropic 네이티브 형식으로 호출합니다
## 2 사례: 왜 동영상 모델에는 전용 그룹이 필요합니까?
동영상 모델은 과금 규칙(초당, 이미지당, 길이당)이 텍스트 모델과 완전히 다르고, 상위 채널도 서로 독립적입니다. 그룹을 사용하면 **특수 과금 규칙이 정확하게 적용됩니다**:
| 모델 | 필수 그룹 |
| -------------------------------- | -------------------------- |
| Sora 2 official video | `Sora2Official` (초당 과금) |
| Alibaba Wan & HappyHorse 동영상 시리즈 | `Wan&HappyHorse` |
| Seedance 2 video | 전용 그룹(정확한 이름은 콘솔에서 확인하십시오) |
잘못된 그룹은 보통 모델을 사용할 수 없음(404), 잘못된 과금, 또는 호출이 아예 거부됨을 의미합니다. token의 “그룹 선택” 또는 “대체 그룹”에 대상 모델과 일치하는 그룹이 포함되어 있는지 확인하십시오.
## 사례 3: "현재 그룹의 업스트림이 포화되었습니다"는 저에게 걸린 요청 제한입니까?
이것은 SaaS 다중 사용자 시나리오에서 자주 나오는 질문입니다. **실제 지원 티켓에서 나온 내용입니다.**
**상황**:
* 개발자: 제 도구는 SaaS 스타일이며, 많은 사용자가 동시에 호출합니다. 트래픽이 늘어나면 다음 오류가 발생합니다:
> `error 429 (content-type-not-allowed)`: 현재 그룹의 업스트림이 포화되었습니다. 나중에 다시 시도하십시오
* 플랫폼이 제 동시 실행 수를 제한하고 있다고 생각했습니다 — 이를 우회하려면 어딘가에서 “그룹을 설정”해야 합니까?
**사실**:
* 이 오류는 **계정 수준의 동시 실행 수 요청 제한이 아닙니다**
* 이는 해당 그룹에서 그 모델에 매핑된 **업스트림 채널**이 현재 바쁘다는 뜻입니다
* 흔한 원인: 공급자 측에서 아직 프리뷰 상태인 모델을 사용하는 경우(`*-preview-*`와 같은 이름의 버전), 공식 처리 용량 자체가 변동합니다
**올바른 대응**:
타임아웃을 늘리고(예: 60–120초) 즉시 재시도는 지수 백오프로 전환합니다. 오류가 발생하는 순간 동시 재시도를 겹쳐서 쌓지 마십시오.
token에 대상 모델에 대응하는 **대체 그룹**을 1\~2개 추가하십시오. 기본 경로가 혼잡할 때 트래픽이 백업 채널로 전환되어 성공률이 높아집니다.
귀사의 비즈니스가 지연 시간이나 안정성에 민감하다면, 동일한 모델 계열에서 더 부하가 안정적인 변형을 자체 시나리오로 **중립적으로 평가**하십시오(대부분의 공급자는 더 가볍고 더 분산된 형제 버전을 제공합니다). 그 트레이드오프는 귀사의 선택입니다.
저희는 고객 호출에 동시 실행 수 장벽을 두지 않습니다. 이 429는 업스트림 채널에서 발생한 것입니다 — **과금 수준의 요청 제한이 아닙니다**. 재시도하면 대개 복구됩니다.
## 그룹을 선택하는 방법 — 빠른 결정
| 사용 상황 | 선택할 그룹 |
| -------------------------------------------------- | -------------------------------------- |
| 텍스트, 멀티모달, NanoBanana, Veo 3.1, 그리고 대부분의 모델 | `Default` |
| Claude + Claude Code에서 국내 코딩 모델(`/v1/messages` 형식) | `ClaudeCode` (기본 5% 할인, 보너스와 중복 적용됩니다) |
| Sora 2 공식 동영상 | `Sora2Official` |
| Wan\&HappyHorse / Seedance 2 동영상 | 각 전용 그룹 |
| 불안정한 고동시 실행 수 워크로드 | token에 1–2개의 **대체 그룹**을 연결합니다 |
## "그룹 배수"에 대하여
콘솔에 표시되는 "그룹 배수"는 **RMB로 책정된 상대값**이며, 직접적인 USD 할인 비율이 아닙니다. `0.14x`은 "86% 할인"을 의미하지 않습니다. 일반적으로 **이 값을 깊게 파고들 필요는 없습니다**. 모델에 맞는 그룹만 선택하면 됩니다. 배수와 가격 변환을 이해하려면 [모델의 배수는 무엇입니까?](/ko/faq/model-multiplier)를 참조하십시오.
## 관련 문서
Token 역할, 생성/편집, 코드 예제 보기, 그룹 개요.
사용량 기준과 호출당 기준 모드의 차이.
배수 의미, RMB 가격 단위, USD 가격 환산.
모델 등급과 사용자 그룹별 접근.