Qwen4-Max API Nasıl Kullanılır?

Qwen4-Max API, milyon token başına 1,50 $/4,50 $ fiyatıyla kullanıma sunuldu. Bu yazıda anahtar nasıl alınır, temel URL nasıl seçilir, düşünme akışı nasıl aktarılır, görseller nasıl gönderilir, araçlar nasıl çağrılır, JSON çıktısı nasıl zorlanır, istemler nasıl önbelleğe alınır ve Anthropic...

INEZA Felin-Michel

INEZA Felin-Michel

16 November 2026

Qwen4-Max API Nasıl Kullanılır?

Kurumsal İçin Apidog

Şirket İçi (On-Premises) Dağıtım

SSO ve RBAC

SOC 2 Uyumlu

Apidog Enterprise'ı Keşfedin

Qwen4-Max API, QwenCloud üzerinde token başına ödeme modeliyle qwen4-max kimliğiyle kullanıma sunuldu. Bulunduğunuz bölgede kullandıkça öde tipinde bir anahtar oluşturun, OpenAI SDK'sını https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 (Singapur) adresine yönlendirin ve çağrıyı yapın. Girdi için milyon token başına 1,50 $, çıktı için 4,50 $ maliyeti var; bağlam penceresi 1M token.

Bu rehber; anahtar, temel URL'ler, düşünme modu, vision, araçlar, yapılandırılmış çıktılar, önbellekleme, Anthropic rotası, limitler ve hataları kapsıyor. Tüm kod örnekleri 16 Kasım 2026 itibarıyla okunduğu haliyle QwenCloud dokümantasyonunu takip ediyor.

Arka plan bilgisi için Qwen4-Max'in ne olduğuna göz atın. Token başına ödeme yerine abonelik erişimi için Qwen4-Max'i kullanmanın tüm yollarına ve Token Planı rehberine bakın.

Qwen4-Max API'nin sunduğu özellikler

Qwen4-Max API, Alibaba'nın amiral gemisi modelinin QwenCloud üzerinden OpenAI uyumlu, Anthropic uyumlu ve DashScope uç noktalarıyla servis edilmiş halidir. Metin, görsel ve video girdisi alır, metin döndürür, varsayılan olarak yanıt vermeden önce düşünür ve function calling, yapılandırılmış çıktılar, bağlam önbellekleme, batch işler, web arama ve ince ayar (fine-tuning) destekler.

qwen4-max model sayfasından alınan sayısal veriler şöyle:

Kalem Değer
Model kimliği qwen4-max
Girdi fiyatı 1M token başına 1,50 $
Çıktı fiyatı 1M token başına 4,50 $
Örtük önbellek girdisi / açık önbellek okuması 1M token başına 0,075 $
Açık önbellek oluşturma 1M token başına 1,875 $ (5 dakika) veya 3 $ (1 saat)
Bağlam penceresi 1M token
Maksimum girdi 991K (düşünme moduyla 983K)
Maksimum çıktı 393K
Maksimum akıl yürütme 262K
Verim 5.000.000 TPM

Düşünme tokenları çıktı tokenı olarak faturalandırılır. Tam maliyet dökümü için Qwen4-Max fiyatlandırma rehberine bakın.

Anahtar edinin ve doğru temel URL'yi seçin

Anahtarlar bir bölgeye bağlıdır ve anahtar tipi uç noktayla eşleşmelidir.

  1. QwenCloud konsolunu açın ve sağ üstteki seçiciden bir bölge seçin.
  2. API Keys bölümüne gidin, Create API key seçeneğine tıklayın, bir açıklama ekleyin ve Generate Key butonuna basın.
  3. Anahtarı hemen kopyalayın; yalnızca bir kez gösterilir. Yeni kullandıkça öde anahtarları sk-ws- ile başlar.
  4. Dışa aktarın: export DASHSCOPE_API_KEY="sk-ws-...".

Her bölge {region}.maas.qwencloudapi.com alan adını kullanır. Singapur ap-southeast-1; Frankfurt eu-central-1, Tokyo ap-northeast-1 ve ABD (Virginia) us-east-1 olur. Ardından protokol yolunu ekleyin:

Protokol Temel URL (Singapur)
OpenAI uyumlu (Chat Completions, Responses) https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
Anthropic uyumlu https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic
DashScope HTTP https://ap-southeast-1.maas.qwencloudapi.com/api/v1
Diagram of one pay-as-you-go qwen4-max key reaching the Singapore domain, which serves three paths: /compatible-mode/v1 for the OpenAI SDK, /apps/anthropic for the Anthropic SDK and /api/v1 for DashScope

Bir Token Planı anahtarı (sk-sp-) yalnızca token-plan.maas.qwencloudapi.com üzerinde çalışır; kullandıkça öde anahtarı ise yalnızca kendi bölgesinin alan adında çalışır. İkisini karıştırmak 401 hatasına yol açar. Bölgeler ve uç noktalar sayfasına bakın.

İlk Qwen4-Max API çağrınız

OpenAI SDK'sını kurun (pip install openai) ve dokümandaki hızlı başlangıç örneğini çalıştırın:

import os
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1"
)
completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{"role": "user", "content": "Summarize the benefits of solar energy in three bullet points."}]
)
print(completion.choices[0].message.content)

qwen4-max için düşünme modu varsayılan olarak açıktır; dolayısıyla bu çağrı akıl yürütme tokenlarını da harcar. Uzun girdiler için akış (streaming) kullanın veya istemci zaman aşımını 180 saniye ve üzerine ayarlayın.

Düşünme modu ve reasoning_content akışı

Qwen4-Max, hibrit bir düşünme modelidir. Dokümandaki varsayılanlar şunlardır: enable_thinking=true, reasoning_effort=high ve thinking_budget=131072. Efor seviyeleri low, high ve xhigh'tur; none düşünmeyi kapatır.

Akıl yürütme ve yanıtı iki aşamalı olarak akışla alın (model sayfasındaki örnekten uyarlanmıştır):

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1",
)
messages = [{"role": "user", "content": "Who are you"}]
completion = client.chat.completions.create(
    model="qwen4-max",
    messages=messages,
    extra_body={"enable_thinking": True},
    stream=True
)
for chunk in completion:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        print(delta.reasoning_content, end="", flush=True)  # phase 1: thinking
    if delta.content:
        print(delta.content, end="", flush=True)            # phase 2: answer

Üç kural:

Düşünmeyi atlamak için {"enable_thinking": False} gönderin.

Görsel ve video girdisi

Görselleri image_url parçaları olarak, videoları video_url parçaları olarak gönderin. Aşağıdaki örnek, modeli qwen4-max olarak ayarlanmış doküman vision örneğinin aynısıdır:

completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/invoice.jpg"}},
      {"type": "text", "text": "Describe what you see in this image"},
    ],
  }],
)

Video için {"type": "video_url", "video_url": {"url": "..."}, "fps": 2} kullanın. Yerel dosyalar Base64 Data URI olarak gönderilir.

Vision rehberine göre her biri 20 MB olan en fazla 2.048 URL görseli, 250 Base64 görseli ve istek başına 64 MB sınırı vardır. Görsel detayı varsayılan olarak yüksektir; bu da daha fazla girdi tokenı maliyetine yol açar.

Function calling

Herhangi bir OpenAI uyumlu modelde olduğu gibi bir tools dizisi gönderin:

tools = [{
  "type": "function",
  "function": {
    "name": "get_current_weather",
    "description": "Useful when you want to check the weather for a specific city.",
    "parameters": {
      "type": "object",
      "properties": {"location": {"type": "string", "description": "City or county, such as Singapore or New York."}},
      "required": ["location"],
    },
  },
}]
completion = client.chat.completions.create(model="qwen4-max", messages=messages, tools=tools)

message.tool_calls alanını okuyun, fonksiyonu çalıştırın, bir tool mesajı ekleyin ve tekrar çağırın.

Düşünme modunda tool_choice yalnızca "auto" veya "none" kabul eder; bir fonksiyonu zorlamak için önce düşünmeyi devre dışı bırakın. Düşünme açıkken araç sonuçlarıyla birlikte reasoning_content alanını geri gönderin, aksi halde doğruluk düşer.

Yapılandırılmış çıktılar

qwen4-max, katı JSON Schema modunu destekler:

completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{"role": "user", "content": "Extract the name and age: Ana is 31."}],
  response_format={
    "type": "json_schema",
    "json_schema": {
      "name": "user_info",
      "strict": True,
      "schema": {
        "type": "object",
        "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
        "required": ["name", "age"],
        "additionalProperties": False,
      },
    },
  },
)

Daha esnek {"type": "json_object"} modunda, bir mesajda "JSON" kelimesi geçmelidir, aksi halde API isteği reddeder. Görsel veya video girdisinde sistem json_object moduna geri düşer; dolayısıyla şema çok kipli (multimodal) çağrılarda zorunlu tutulmaz.

Bağlam önbelleği ve batch

Önbellek. Ayar yapılmadığında, örtük önbellek önekleri eşleştirir ancak isabet garantisi vermez. Deterministik isabet için Qwen4 açık önbelleğini kullanın: bir içerik bloğunu "prompt_cache_breakpoint": {"mode": "explicit"} ile işaretleyin (mesajın content alanı bir dizi olmalıdır) ve TTL'i extra_body={"prompt_cache_options": {"mode": "explicit", "ttl": "5m"}} ile belirleyin. TTL 5m veya 1h olabilir; önbelleğe alınan önek en az 1.024 token olmalıdır. Okumalar milyon token başına 0,075 $ maliyetlidir — taze girdiden %95 daha ucuz.

Batch. Batch rehberine göre girdi ve çıktı, gerçek zamanlı fiyatın %50'si üzerinden faturalandırılır ve sonuçlar 24 saat içinde döner. qwen4-max için Batch File, Singapur dışında tek bir bölgede çalışır ve bağlam önbellekleme desteklemez; dolayısıyla bu özelliğe dayalı bir pipeline kurmadan önce batch rehberini kontrol edin.

Anthropic uyumlu rota

Zaten Anthropic SDK'sıyla mı çalışıyorsunuz? Yalnızca temel URL'yi ve anahtarı değiştirin:

import anthropic
import os

client = anthropic.Anthropic(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic",
)
message = client.messages.create(
    model="qwen4-max",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Who are you?"}],
    thinking={"type": "disabled"},
)
print(message.content)

Bu örnek, dokümanın kendi örneğinde olduğu gibi düşünmeyi kapatıyor. Temel URL'yi /apps/anthropic ile bitirin. /v1/ eklemek /v1/v1/... üretir ve 404 döndürür. Burada da düşünme varsayılan olarak açıktır ve düşünme etkinleştirildiğinde max_tokens değeri düşünme bütçesinden büyük olmalıdır. Efor ayarı output_config.effort ile yapılır (low, high, xhigh); yerleşik web_search ve web_fetch araçları bu rotada kullanılabilir.

Qwen4-Max API hız limitleri

Hız limitleri sayfasından:

Bölge RPM TPM
Singapur Dinamik Dinamik katmanlar: 5M, 10M, 20M
Frankfurt, Tokyo, ABD (Virginia) ve diğer Global kapsamlı bölgeler 30.000 5.000.000

Limitler bölge başına hesap bazında ve ayrıca saniye başına uygulanır (RPS = RPM / 60); dolayısıyla ani bir yük artışı sizi dakikalık toplamın altında kısıtlayabilir.

Ücretsiz kota sayfasına göre ücretsiz kota yalnızca Singapur'da bulunur, model başınadır (tipik olarak 1.000.000 token), 90 gün geçerlidir ve dosyada ödeme bilgisi gerektirir. Sayfa qwen4-max için bir kota belirtmiyor; dolayısıyla konsoldaki Free Tier sayfasını kontrol edin veya Qwen4-Max'i ücretsiz nasıl kullanabileceğinize göz atın.

Yaygın Qwen4-Max API hataları

Kod Anlamı Çözüm
401 InvalidApiKey Anahtar ve temel URL farklı bölgelerden geliyor ya da bir Token Planı anahtarı kullandıkça öde uç noktasına gönderildi URL ile aynı bölgede oluşturulmuş bir anahtar kullanın
400 InvalidParameter Genellikle düşünme açıkken max_tokens değerinin 1 ile 32.768 aralığının dışında olması max_completion_tokens kullanmaya geçin
403 AllocationQuota.FreeTierOnly Ödeme bilgisi ayarlanmadan ücretsiz kotanın tükenmesi Free Tier sayfasına ödeme bilgisi ekleyin
404 ModelNotFound qwen4-max, çağrı yaptığınız bölgede sunulmuyor O bölge için Model fiyatlarını kontrol edin
429 Throttling RPM veya TPM limitine ulaşıldı Geri çekilip tekrar deneyin veya yükü saniyelere dağıtın

Kodlama ajanınızın Qwen4-Max API'yi Apidog CLI ile test etmesine izin verin

Kodlama ajanınız entegrasyonu yazıyorsa regresyon testini de yazsın. Apidog CLI, uç noktayı kaydetmesini, anahtarı saklamasını ve doğrulamaları çalıştırmasını sağlar.

Flow from one prompt to a coding agent, which runs apidog environment create, endpoint create, test-case create with assertions on status, choices, usage and reasoning_content, then apidog run for a pass or fail report

Tek seferlik kurulum:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Ardından ajanınıza tek bir komut verin:

In Apidog project <projectId>, create an environment "Qwen Singapore" with base URL
https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 and a secret
variable DASHSCOPE_API_KEY. Add POST /chat/completions with a Bearer auth header,
model qwen4-max and enable_thinking true. Create a test case asserting status 200,
a non-empty choices array, a usage object, and reasoning_content present on the
first choice's message. Run it and summarize any failures.

Ajan, yazmadan önce her payload şemasını okur ve ardından testi çalıştırır:

apidog environment create "Qwen Singapore" --project <projectId> --base-url https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
apidog cli-schema get environment-update
apidog environment update <envId> --project <projectId> --file env.json
apidog cli-schema get endpoint-create
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

cli raporlayıcısı geçti veya kaldı çıktısı verir; json ise ajanın okuyabileceği bir rapor yazar. Aynı apidog run ... -r junit komutunu Apidog CLI CI/CD rehberiyle CI'a taşıyın; daha fazla komut örneği için Claude Code'da Apidog CLI yazısına bakın. Apidog'un Ücretsiz planı 4 kullanıcıya kadar kapsar.

SSS

Qwen4-Max API'nin model kimliği nedir?

Sabit kimlik qwen4-max'tir. Önceki qwen4-max-preview kimliği, 11 Kasım 2026'da başlayan önizleme süresince yalnızca Token Planı için kullanılıyordu.

Qwen4-Max API OpenAI uyumlu mu?

Evet. Chat Completions ve Responses API için OpenAI SDK'sını /compatible-mode/v1 temel URL'siyle kullanın. Ayrıca Anthropic uyumlu bir uç nokta ve DashScope API de mevcuttur.

Qwen4-Max API'de düşünmeyi nasıl kapatırım?

extra_body={"enable_thinking": False} gönderin. reasoning_content alanını kaybedersiniz, ancak gecikme ve çıktı tokenları azalır. Modelleri karşılaştırıyor musunuz? Qwen4-Max vs Qwen3.8 yazısına bakın.

Qwen4-Max API'nin maliyeti nedir?

Milyon girdi tokenı başına 1,50 $ ve milyon çıktı tokenı başına 4,50 $; önbelleğe alınmış okumalar milyonda 0,075 $.

Token Planı anahtarımı token başına ödeme API'siyle kullanabilir miyim?

Hayır. Token Planı anahtarları (sk-sp-) yalnızca token-plan.maas.qwencloudapi.com üzerinde çalışır; kullandıkça öde anahtarları ise yalnızca kendi bölgesinin alan adında çalışır.

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin