> ## 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.

# Qwen4-Max 플래그십 멀티모달 모델 | APIYI

> Qwen4-Max(qwen4-max)는 네이티브 비전, 도구 호출 및 약 1M 컨텍스트를 제공합니다. APIYI 가격은 1M tokens당 입력 $1.50, 출력 $4.50, 캐시된 입력 $0.075이며, 325회의 테스트 호출을 통해 확인되었습니다.

Qwen4-Max (`qwen4-max`)는 Alibaba의 Qwen4 시리즈를 대표하는 모델입니다. 2조 4천억 개 파라미터의 백본은 복잡한 추론, 코딩 에이전트, 장문서 분석 및 전문 워크플로를 위해 텍스트, 이미지 및 동영상 입력을 기본 지원합니다. 이 모델은 국제 제공업체 사이트와 동일한 정가로 APIYI에서 제공되며, **출시 전 테스트 호출 325회**와 **Default 그룹에서의 출시 검증 15회**를 거쳤습니다.

> [!NOTE]
>
> **모델 이름: `qwen4-max`**. Default, SVIP, CodexResponses 및 ClaudeCode 그룹에서 사용할 수 있으며, Chat Completions, Responses 및 Messages 엔드포인트가 개방되어 있습니다. 추론은 기본적으로 활성화되어 있습니다. 일상적인 채팅에서는 `reasoning_effort="none"`를 설정하여 추론 token 사용량을 줄일 수 있습니다.

## 이 모델을 선택하는 이유

> [card] 제공업체 가격 및 충전 보너스
>
> 입력 \$1.50, 출력 \$4.50, 캐시된 입력은 100만 token당 \$0.075입니다. [충전 보너스](https://docs.apiyi.com/ko/faq/recharge-promotions.md) 10％–20％를 적용하면 실제 요율은 정가의 약 83–91％입니다.

> [card] 약 100만 컨텍스트 검증 완료
>
> 입력 951,498 token을 사용한 요청에서 92.3초 만에 중간과 끝부분의 마커를 모두 정확히 불러왔습니다. 보고된 입력 상한은 991,808 token입니다.

> [card] 네이티브 멀티모달 입력
>
> 텍스트, 이미지 및 동영상 입력을 모두 테스트했습니다. 이미지 OCR과 두 이미지 식별은 세 제공업체 엔드포인트 모두에서 통과했으며, 채팅 동영상 이해 기능은 테스트 영상을 정확하게 설명했습니다.

> [card] 완전한 에이전트 도구 루프
>
> 단일, 병렬, 강제, 이름 지정 및 스트리밍 도구 호출과 전체 2라운드 도구 결과 재생이 모두 통과했습니다.

## 엔드포인트 및 그룹

| 엔드포인트 | 사용 가능 여부 및 권장 그룹 |
| - | - |
| `/v1/chat/completions` | 공개됨; 일반 사용에는 Default 및 SVIP 권장 |
| `/v1/responses` | 공개됨; Codex / Responses 클라이언트에는 CodexResponses 권장 |
| `/v1/messages` | 공개됨; Claude Code 클라이언트에는 ClaudeCode 권장 |
| 그룹 | Default, SVIP, CodexResponses, ClaudeCode |
| 과금 | 사용량 기반 - 채팅 |

세 엔드포인트 모두 공개되어 있습니다. 이는 클라이언트별 그룹 권장 사항이며, 다른 그룹의 사용을 제한하는 것이 아닙니다. 최소한의 Responses 및 Messages 요청도 Default 그룹의 token으로 성공했으며, 각 token에서 사용할 수 있는 그룹은 해당 token의 콘솔 구성에 따라 결정됩니다.

## 가격

충전 보너스 적용 전 100만 token 기준:

| 항목 | APIYI | 해외 제공업체 사이트 |
| - | -: | -: |
| 입력 | **\$1.50** | \$1.50 |
| 추론을 포함한 출력 | **\$4.50** | \$4.50 |
| 캐시된 입력 | **\$0.075** | \$0.075 |

가격은 해외 Qwen4-Max 제공업체 사이트와 동일하며 변경될 수 있습니다. 현재 요율은 [모델 가격](https://docs.apiyi.com/ko/models/index.md)에서 확인하시기 바랍니다. 충전 보너스를 적용하면 실제 요율은 정가의 약 83–91％입니다. [충전 프로모션](https://docs.apiyi.com/ko/faq/recharge-promotions.md)을 참조하시기 바랍니다.

## 사양 및 측정값

| 항목 | 사양 또는 측정값 |
| - | - |
| 모델 ID | `qwen4-max` |
| 아키텍처 | Qwen4 희소 MoE; 2.4T 백본 파라미터, token당 71B 활성화, 추가로 328B N-gram 임베딩 파라미터 |
| 컨텍스트 | 제공업체가 1M이라고 주장함; 입력 951,498 tokens 검증 |
| 입력 제한 오류 | `Range of input length should be [1, 991808]` |
| 입력 모달리티 | 텍스트, 이미지, 동영상 |
| 사고 | 기본적으로 활성화됨; `none` / `off`으로 비활성화 |
| 채팅 비스트리밍 지연 시간 | P50 5.65초, P95 8.16초 |
| 채팅 첫 token까지 시간 | P50 3.93초 |
| 채팅 출력 속도 | P50 14.93 tokens/s |
| 채팅 동시 실행 수 | 12/12 성공; 실제 소요 시간 10.9초 |

이 측정값은 2026-11-17 (UTC+8)의 출시 전 테스트 기간에 얻은 결과이며, 장기 SLA를 보장하지 않습니다.

## 사고 및 출력 예산

`reasoning_effort`는 `none`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh` 및 `max`을 허용합니다. 유효하지 않은 값은 허용되는 집합을 나열한 400을 반환합니다.

* `none` / `off`: 일반적인 채팅, 추출 및 고빈도 호출에서 사고를 비활성화합니다.
* `minimal` / `low` / `medium`: 일부 추론을 유지합니다. 간단한 작업에서는 token 사용량이 단조롭게 증가하지 않을 수 있습니다.
* `high` / `xhigh` / `max`: 테스트에서 더 많은 추론을 생성했으며 복잡한 작업에 더 적합합니다.
* `reasoning_effort`과 `thinking_budget`은 상호 배타적입니다. 둘 다 전송하면 400을 반환합니다.

```python theme={null}
resp = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "Explain load balancing in one sentence."}],
    reasoning_effort="none",
    max_tokens=500,
)
```

> [!WARNING]
>
> **Qwen4-Max에서는 `max_tokens`가 추론과 표시되는 출력을 함께 포함합니다.** 작은 예산이 추론에 전부 소진되어, content가 비어 있고 `length` finish reason이 포함된 HTTP 200이 반환될 수 있습니다. `reasoning_effort`를 사용하여 비용을 제어하고, 답변 자체를 위한 `max_tokens`를 충분히 남겨 두십시오.

## 코드 예시

### Python (OpenAI SDK 호환)

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.apiyi.com/v1",
)

resp = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {"role": "user", "content": "Prove that among any 5 integers, some 3 sum to a multiple of 3."}
    ],
    reasoning_effort="xhigh",
    max_tokens=4000,
)

print(resp.choices[0].message.content)
```

### 이미지 입력

```python theme={null}
import base64

with open("chart.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

resp = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Read the number in this image and return only the number."},
        {"type": "image_url", "image_url": {
            "url": f"data:image/png;base64,{image_b64}"
        }},
    ]}],
    max_tokens=500,
)
```

base64와 원격 이미지 URL 모두 공급자 채널 테스트를 통과했습니다. 동영상의 경우 `video_url`이(가) 포함된 base64 데이터 URL 또는 `{"type": "video", "video": [...]}`의 프레임 시퀀스를 사용합니다. 프레임 시퀀스에는 4\~80개의 프레임이 필요합니다.

### cURL

```bash theme={null}
curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen4-max",
    "messages": [{"role": "user", "content": "Hello"}],
    "reasoning_effort": "none",
    "max_tokens": 500
  }'
```

## 도구 호출

채팅 완성은 단일 및 병렬 도구, `parallel_tool_calls=false`, `tool_choice="required"`, 명명된 도구, 비활성화된 도구, 스트리밍 도구 델타 및 전체 2회차 도구 결과 재생에 대한 사전 출시 테스트를 통과했습니다.

```python theme={null}
resp = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "Check the weather in Beijing."}],
    tools=tools,
    tool_choice={"type": "function", "function": {"name": "get_weather"}},
    max_tokens=1000,
)
```

여러 후보 답변에는 `n > 1`을 `reasoning_effort="none"`와 함께 사용합니다. 추론이 활성화된 동안에는 `n > 1`가 400을 반환합니다.

## 구조화된 출력

`response_format={"type": "json_schema"}`가 중첩 객체, 배열, 열거형 및 `additionalProperties: false`에 대한 테스트를 통과했습니다. 스트리밍 응답에서도 유효한 JSON이 생성되었습니다.

> [!TIP]
>
> 엄격한 추출에는 `reasoning_effort="none"`와 함께 `json_schema`를 사용하는 것이 좋습니다. 기본 `json_object`는 구문 분석 가능한 JSON만 보장합니다. 테스트에서는 여전히 최상위 배열이 생성되었으므로 스키마 검증을 대신할 수 없습니다.

## 컨텍스트 캐싱

* 약 170 token으로 구성된 짧은 접두사는 적중하지 않았으며, 더 긴 고정 접두사에서는 캐시 읽기가 발생했습니다.
* 명시적 채팅 `cache_control`은 이후 모든 출시 전 호출에서 1,657 token에 적중했으며, APIYI 기본 그룹의 두 번째 출시 확인에서도 1,657 token에 적중했습니다. 암시적 캐시 적중은 일관성이 낮았습니다.
* 캐시된 입력에는 100만 token당 \$0.075가 부과됩니다.

> [!WARNING]
>
> **사용량의 캐시 필드는 과금 명세가 아닙니다.** 적중 여부, 캐시된 token 수 및 최종 할인을 확인하려면 개별 콘솔 로그의 과금 세부 정보를 사용하십시오.

## 매개변수 호환성

| 매개변수 | 관찰된 동작 |
| - | - |
| `temperature` | `1.5`은 작동하지만, `2.0`는 범위 오류를 반환합니다. 지원 범위: `[0.0, 2.0)` |
| `top_p` | 지원 범위: `(0.0, 1.0]` |
| `top_k` / `presence_penalty` / `frequency_penalty` | 지원됩니다 |
| `stop` | 잘라내기가 작동합니다 |
| `logprobs` / `top_logprobs` | 지원됩니다 |
| `partial: true` | 접두사 이어쓰기가 작동합니다 |
| `prefix: true` | 정상적인 이어쓰기를 생성하지 않았습니다. `partial`를 사용하십시오 |
| `n > 1` | thinking을 비활성화해야 합니다 |
| `seed` | 동일한 시드에서 서로 다른 출력이 생성되었습니다. 결정성은 보장되지 않습니다 |
| 알 수 없는 매개변수 | 자동으로 무시될 수 있으므로 이 동작에 의존하지 마십시오 |

공급자는 `max_tokens=131072` 및 `200000`을 허용하고 짧은 답변을 반환했습니다. 이는 해당 값이 거부되지 않았다는 것만 보여 주며, 해당 길이로 생성되는지는 검증하지 않습니다.

## FAQ

> [accordion] HTTP 200과 빈 응답을 받은 이유는 무엇입니까?
>
> 기본 추론은 소량의 `max_tokens` 예산을 소비하여 표시할 콘텐츠가 남지 않고 `length` 종료 사유가 반환될 수 있습니다. 사고 기능을 비활성화하거나 출력 예산을 늘린 다음, `reasoning_content` 및 `finish_reason`을 확인하십시오.

> [accordion] Responses 또는 Claude Code를 직접 사용할 수 있습니까?
>
> 가능합니다. Responses 클라이언트에는 CodexResponses 그룹을, Claude Code에는 ClaudeCode를 사용하십시오. 세 엔드포인트 모두에 대한 최소 요청은 기본 그룹 token으로도 통과했습니다. 공급자 테스트에서는 Responses의 `tool_choice="required"`을 무시했으므로, 강제 구조화 호출에는 이름이 지정된 도구나 채팅을 사용하는 것이 좋습니다. Messages는 OpenAI 스타일의 `response_format`을 지원하지 않으며 `max_tokens`이 필요합니다. 구조화된 출력에는 도구 호출을 사용하십시오. 광범위하게 배포하기 전에 복잡한 Claude Code 에이전트 워크플로를 클라이언트 버전에 맞게 검증하십시오.

> [accordion] 일상적인 사용 비용을 줄이려면 어떻게 해야 합니까?
>
> 일상적인 채팅과 구조화된 추출에는 `reasoning_effort="none"`을 설정하고, 긴 문서에는 고정 접두사를 재사용하며, 콘솔에서 캐시 과금을 확인하고, 적용 가능한 충전 보너스 등급을 사용하십시오.

> [accordion] 최대 출력 200K를 광고해도 됩니까?
>
> 안 됩니다. `max_tokens=200000`을 수락한다고 해서 200K 출력이 생성되었다는 의미는 아닙니다. 이 페이지에서는 해당 결과를 기반으로 최대 출력 길이를 지정하지 않습니다.

## 관련 문서

* [모델 가격](https://docs.apiyi.com/ko/models/index.md) — 현재 가격, 그룹 및 엔드포인트
* [충전 프로모션](https://docs.apiyi.com/ko/faq/recharge-promotions.md) — 보너스 등급 및 유효 요율
* [Qwen3.8-Max 개요](https://docs.apiyi.com/ko/api-capabilities/qwen-3-8/overview.md) — 이전 세대
* [API 매뉴얼](https://docs.apiyi.com/ko/api-manual.md) — 인증, 요청 및 오류 처리

> [!NOTE]
>
> 측정값은 2026-11-17 (UTC+8)에 수행한 출시 전 호출 325건과, 같은 날 APIYI 기본 그룹에서 수행한 출시 확인 15건을 기반으로 합니다. 여기에는 Chat Completions, Responses, Messages, 스트리밍, tools, JSON 스키마, 이미지, 동영상, 캐싱 및 32K 컨텍스트가 포함됩니다. 제공업체 참조: `https://qwen.ai/blog?id=qwen4-max`. 모델 및 채널 동작은 변경될 수 있으며, 실제 응답과 콘솔 과금 세부 정보가 기준 정보입니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.