DashScope Üzerinden Qwen Image 3 Pro API Nasıl Kullanılır: Bir Geliştirici Eğitimi

DashScope Üzerinden Qwen Image 3 Pro API Nasıl Kullanılır: Bir Geliştirici Eğitimi

Alibaba'nın qwen-image-3.0-pro modeli, Model Studio veya DashScope olarak da bilinen Bailian aracılığıyla sunulan amiral gemisi görüntü oluşturma modelidir. Tahmin edilebilir fiyatlandırma ile güvenilir bir metinden görüntüye uç noktasına ihtiyaç duyan arka uç geliştiricilerini hedefler. Resmi model kimliği qwen-image-3.0-pro, Alibaba'nın Model Studio kataloğunda belgelenmiştir (Alibaba Cloud Model Studio belgeleri, 2026) ve herhangi bir HTTP istemcisinden çağırabilirsiniz.

Bu eğitim, tam entegrasyonu adım adım açıklar. Sonunda, bir API anahtarına, çalışan bir cURL çağrısına, bir Python kod parçacığına ve görüntü başına maliyet yapısının net bir görünümüne sahip olacaksınız.

Temel Çıkarımlar

• Model Kimliği: qwen-image-3.0-pro, Alibaba Cloud Model Studio / DashScope üzerinde https://dashscope-us.aliyuncs.com/api/v1 adresinde sunulmaktadır (Alibaba Cloud, 2026).
• Kimlik Doğrulama: DASHSCOPE_API_KEY'i bir ortam değişkeni olarak ayarlayın, ardından bir Bearer token olarak gönderin (Promptfoo, 2026).
• Referans fiyat: Önceki sürüm qwen-image-2.0-pro, Alibaba resmi fiyatlandırmasına göre oluşturulan görüntü başına 0,075 ABD doları tutarındadır (Alibaba Cloud fiyatlandırması, 2026).
• Her görüntü modelinin, ödeme yapmadan önce test için ücretsiz bir kotası vardır (Alibaba Image API SSS, 2026).

Önkoşullar

Herhangi bir kod yazmadan önce, Model Studio erişimi olan bir Alibaba Cloud hesabınız olduğunu doğrulayın. Resmi "Qwen'e İlk API Çağrısı" kılavuzu, her geliştiricinin ihtiyaç duyduğu üç şeyi listeler: Model Studio konsolunda oluşturulmuş bir API Anahtarı, projenize bağlı bir Çalışma Alanı Kimliği ve DashScope HTTP uç noktasına erişim (Alibaba Cloud, 2026).

Temel araçlara da ihtiyacınız var. cURL'li bir terminal, Python 3.9 veya daha yenisi ve requests kütüphanesi bu eğitimdeki her şeyi kapsar. Tescilli bir SDK gerekmez. Daha önce bir betikten OpenAI API'sini çağırdıysanız, DashScope deseni tanıdık gelecektir, çünkü her ikisi de Bearer token'ları ve JSON istek gövdeleri kullanır.

Önerilen bir desen, her ortam için özel bir Çalışma Alanı tutmaktır, böylece hazırlık anahtarları asla üretim kotalarına dokunmaz. Bu ayrım, ay sonunda maliyet atamasını da daha temiz hale getirir.

Adım 1: API Anahtarınızı ve Çalışma Alanı Kimliğinizi Alın

API Anahtarı, qwen-image-3.0-pro'ya yaptığınız her çağrıyı yetkilendiren kimlik bilgisidir. Alibaba'nın başlangıç kılavuzu, geliştiricilere anahtarı Model Studio konsolunda oluşturmalarını ve ardından Çalışma Alanı Kimliğini aynı panodan kopyalamalarını talimat verir (Alibaba Cloud, 2026). Her iki değeri de sır olarak kabul edin.

Bunları almak için:

1. Alibaba Cloud portalındaki Model Studio konsoluna giriş yapın.
2. API Anahtarları bölümünü açın ve API Anahtarı Oluştur'a tıklayın.
3. Oluşturulan anahtarı hemen kopyalayın. Konsol, oluşturulduktan sonra tam değeri gizler.
4. Panonun üst kısmında görüntülenen Çalışma Alanı Kimliği'ni not alın.

Anahtarı bir parola yöneticisinde veya ekibinizin gizli arka ucunda saklayın. Kaynak dosyalarına yapıştırmayın. Çalışma Alanı Kimliği daha az hassastır ancak yine de satır içi yerine yapılandırmada tutmaya değerdir.

Alıntı özeti: Alibaba'nın resmi "Qwen'e İlk API Çağrısı" kılavuzu, geliştiricilere Model Studio konsolunda bir API Anahtarı oluşturmalarını, Çalışma Alanı Kimliğini aynı panodan kopyalamalarını ve modelleri https://dashscope-us.aliyuncs.com/api/v1 adresindeki DashScope uç noktası aracılığıyla çağırmalarını talimat verir (Alibaba Cloud, 2026).

Adım 2: DASHSCOPE_API_KEY Ortam Değişkenini Ayarlayın

Anahtarı bir ortam değişkenine yüklemek, onu kodunuzdan ve sürüm kontrolünden uzak tutar. Promptfoo tarafından belgelenen topluluk deseni, betiğinizi çalıştırmadan önce DASHSCOPE_API_KEY adlı bir değişken ayarlamaktır, bu değişken daha sonra istek zamanında HTTP istemcisi tarafından okunur (Promptfoo, 2026).

macOS ve Linux'ta:

export DASHSCOPE_API_KEY="sk-anahtarınız-burada"

Windows PowerShell'de:

$env:DASHSCOPE_API_KEY = "sk-anahtarınız-burada"

Kalıcı bir kurulum için, dışa aktarma satırını ~/.zshrc, ~/.bashrc veya Windows kullanıcı ortam değişkenlerinize ekleyin. Ardından terminalinizi yeniden başlatın. Devam etmeden önce değişkenin yüklendiğini doğrulayın:

echo $DASHSCOPE_API_KEY

Ortak bir kurulum, .env dosyası artı python-dotenv gibi bir yükleyici kullanmaktır, böylece aynı yapılandırma yerel geliştirme, CI ve konteyner dağıtımlarında çalışır. Anahtarın asla kaydedilmemesi için .env'i .gitignore'a eklemeyi unutmayın.

Adım 3: cURL ile İlk Görüntü Oluşturma Çağrınızı Yapın

https://dashscope-us.aliyuncs.com/api/v1 adresindeki DashScope uç noktası, qwen-image-3.0-pro dahil olmak üzere her Qwen modeli için giriş noktasıdır (Alibaba Cloud, 2026). Çağrılar, Authorization başlığında bir Bearer token'ı ve modeli ve isteminizi adlandıran bir JSON gövdesi kullanır.

Aşağıda, belgelenmiş uç nokta ve kimlik doğrulama desenine dayalı açıklayıcı bir cURL isteği bulunmaktadır. Alan adları ve tam istek yolları DashScope kuralına uyar, ancak üretime göndermeden önce geçerli şemayı resmi API referansına karşı onaylamalısınız DashScope aracılığıyla Qwen API adresinde.

# Açıklayıcı örnek. Tam alan adlarını ve yollarını şuna göre onaylayın:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
curl -X POST "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "input": {
      "prompt": "Sonbaharda şirin bir kitapçı kafe, sıcak ışık, yüksek detaylı"
    },
    "parameters": {
      "size": "1024*1024",
      "n": 1
    }
  }'

Birkaç pratik not:

• Bazı DashScope görüntü uç noktaları asenkrondur, yani ilk yanıt bir görev kimliği döndürür ve bitmiş görüntüyü almak için ikinci bir URL'yi sorgularsınız. qwen-image-3.0-pro'nun tam davranışı için API referansını kontrol edin.
• İstemleri belgelenmiş token limiti altında tutun. Uzun istemler sessizce kesilebilir.
• Desteklenen en boy oranlarından birine uyan size parametresini kullanın, aksi takdirde çağrı varsayılana geri dönebilir.

Alıntı özeti: https://dashscope-us.aliyuncs.com/api/v1 adresindeki resmi DashScope uç noktası, qwen-image-3.0-pro'yu sunar ve Alibaba Cloud tarafından belgelenmiş tam giriş ve çıkış parametre referansına sahiptir (Alibaba Cloud, 2026).

Adım 4: Yanıtı Python'da Ayrıştırın

Python, görüntü API'lerini sarmak için en yaygın dildir çünkü requests kütüphanesi JSON ayrıştırmayı önemsiz hale getirir. Çağrı döndüğünde, oluşturulan görüntü URL'sini çıkarır, indirir ve diske veya nesne depolamaya kalıcı hale getirirsiniz.

İşte kısa bir açıklayıcı betik. cURL'de olduğu gibi, bunlara güvenmeden önce yanıt alan adlarını resmi API referansına karşı onaylayın.

# Açıklayıcı örnek. Yanıt şemasını şuna göre onaylayın:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
ENDPOINT = "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "qwen-image-3.0-pro",
    "input": {
        "prompt": "Sonbaharda şirin bir kitapçı kafe, sıcak ışık, yüksek detaylı"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}

response = requests.post(ENDPOINT, headers=headers, json=payload)
response.raise_for_status()
data = response.json()

# Aşağıdaki alan adları açıklayıcıdır. Resmi API referansına göre doğrulayın.
image_url = data["output"]["results"][0]["url"]
print("Oluşturulan görüntü URL'si:", image_url)

# Dosyayı indirin
img = requests.get(image_url)
with open("output.png", "wb") as f:
    f.write(img.content)

Birkaç üretim düzeyinde ipucu:

• Çağrıyı üstel geri çekilmeyle retry içine sarın. Ağ aksaklıkları olur.
• Bir zaman aşımı ekleyin. Görüntü oluşturma birkaç saniye sürebilir.
• Alibaba desteğinin hataları izleyebilmesi için genellikle bir yanıt başlığında döndürülen tam istek kimliğini günlüğe kaydedin.

API istemcisi ile iş mantığı arasına ince bir soyutlama katmanı eklemek yardımcı olur. Bu şekilde, modelleri daha sonra değiştirmek (örneğin bir düzenleme uç noktasına veya daha yeni bir Qwen sürümüne) yalnızca bir modülü değiştirir.

Qwen Image 3 Pro Ne Kadara Mal Olur?

Fiyatlandırma, oluşturulan görüntü başına yapılır ve Alibaba yalnızca başarılı oluşturmalar için faturalandırır. Resmi fiyatlandırma sayfasında qwen-image-2.0-pro görüntü başına 0,075 ABD doları olarak listelenir (Alibaba Cloud fiyatlandırması, 2026). Üçüncü taraf sağlayıcılar, Qwen görüntü modellerini farklı fiyat noktalarında sunar: Fal, bir Qwen görüntü modelini yaklaşık görüntü başına 0,021 ABD doları olarak listeler ve Replicate, 1024x1024'te yaklaşık görüntü başına 0,030 ABD doları ücret alır (Puter fiyatlandırma dökümü, 2026; pricepertoken, 2026).

Özellikle qwen-image-3.0-pro için, 2.0-pro fiyatını en yakın resmi referans olarak kabul edin, ardından bütçeleme yapmadan önce Model Studio fiyatlandırma sayfasındaki güncel rakamı doğrulayın.

Alıntı özeti: Alibaba'nın Model Studio'su qwen-image-2.0-pro'yu oluşturulan görüntü başına 0,075 ABD doları olarak fiyatlandırır ve yalnızca başarılı oluşturmaları faturalandırır; Fal ve Replicate gibi üçüncü taraf sağlayıcılar ise Qwen görüntü modellerini sırasıyla yaklaşık görüntü başına 0,021 ABD doları ve 0,030 ABD doları olarak listeler (Alibaba Cloud, 2026; Puter, 2026).

Küçük bir uygulama için aylık tahmini bütçe şöyle görünebilir:

Fiyatlar Temmuz 2026 itibarıyla.

Ücretsiz Kota ve Limitler

Model Studio'daki her görüntü modeli ücretsiz bir kota ile birlikte gelir, böylece harcama yapmadan önce test edebilirsiniz (Alibaba Image API SSS, 2026). Kota, SSS'de belgelenen bir programa göre sıfırlanır.

Birkaç pratik ipucu:

• İstem şablonlarını ve parametre kombinasyonlarını doğrulamak için ücretsiz kotayı kullanın.
• Ücretli katmanlara geçtiğinizde sürpriz faturalardan kaçınmak için Model Studio panosundaki kullanımı izleyin.
• Testleriniz aniden kota hatalarıyla başarısız olmaya başlarsa, ücretsiz katmanın süresinin dolup dolmadığını veya Çalışma Alanlarını değiştirip değiştirmediğinizi iki kez kontrol edin.

Metinden Görüntüye Ötesi: Düzenleme API'si

Qwen ailesi, özel bir görüntü düzenleme uç noktası da içerir. Çoklu görüntü girişi ve çıkışı, görüntü içi metin düzenleme, nesne ekleme, kaldırma ve taşıma ve poz değişikliklerini destekler (Qwen-Image Edit API, 2026).

Bu önemlidir çünkü düzenleme çağrıları, metinden görüntüye çağrılarından farklı bir istek şekli kullanır. Ürününüz arka plan değişimi veya nesne kaldırma gerektiriyorsa, kendi parametreleri ve fiyatlandırması olan ayrı bir uç noktaya isabet edeceksiniz. İki entegrasyon yolu planlayın: biri oluşturma için, diğeri düzenleme için.

SSS

Qwen Image 3 Pro için model kimliği nedir?

Resmi model kimliği qwen-image-3.0-pro'dur ve Alibaba Cloud Model Studio / DashScope üzerinde https://dashscope-us.aliyuncs.com/api/v1 adresinde sunulmaktadır (Alibaba Cloud, 2026). İstek gövdenizin model alanında bu tam dizeyi kullanın.

DashScope API çağrılarını nasıl doğrularım?

DASHSCOPE_API_KEY ortam değişkenini ayarlayın, ardından her isteğin Authorization başlığında bir Bearer token olarak gönderin (Promptfoo, 2026). Anahtarı asla kaynak dosyalarına sabit kodlamayın veya sürüm kontrolüne kaydetmeyin.

Qwen Image 3 Pro görüntü başına ne kadara mal olur?

Alibaba, önceki sürüm qwen-image-2.0-pro'yu görüntü başına 0,075 ABD doları olarak fiyatlandırır ve yalnızca başarılı oluşturmaları faturalandırır (Alibaba Cloud fiyatlandırması, 2026). Fal ve Replicate gibi üçüncü taraf sağlayıcılar, Qwen görüntü modellerini yaklaşık görüntü başına 0,021 ABD doları ve 0,030 ABD doları olarak listeler. Güncel 3.0-pro fiyatlandırmasını resmi sayfadan doğrulayın.

Ücretsiz kota var mı?

Evet. Model Studio'daki her görüntü modelinin, ücretli faturalandırma başlamadan önce test için kullanabileceğiniz ücretsiz bir kotası vardır (Alibaba Image API SSS, 2026). Modele göre değişen sıfırlama sıklığı ve limitler için SSS'yi kontrol edin.

Qwen Image 3 Pro görüntü düzenlemeyi destekliyor mu?

Düzenleme, çoklu görüntü G/Ç'yi, görüntüler içinde metin düzenlemeyi, nesne ekleme, kaldırma ve taşıma ve poz değişikliklerini destekleyen Qwen-Image Edit adlı ayrı bir uç nokta tarafından ele alınır (Qwen-Image Edit API, 2026). Metinden görüntüye ve düzenleme API'leri farklı istek şekillerine sahiptir.

Sonuç

Artık ilk qwen-image-3.0-pro çağrınız için tam yola sahipsiniz: Model Studio konsolundan bir API Anahtarı, yüklü DASHSCOPE_API_KEY ortam değişkeni, çalışan bir cURL isteği ve sonucu ayrıştıran ve indiren bir Python kod parçacığı. Alibaba resmi fiyatlandırmasında 0,075 ABD dolarından başlayan görüntü başına fiyatlandırma modeli, ölçeklendikçe maliyeti tahmin edilebilir hale getirir.

İki sonraki adım entegrasyonunuzu keskinleştirecektir. İlk olarak, şema ayrıntıları model sürümleri arasında değişebileceğinden, DashScope aracılığıyla Qwen API adresindeki resmi API referansına karşı tam istek ve yanıt alan adlarını onaylayın. İkinci olarak, ürününüz saf oluşturma yerine düzenlemeler gerektiriyorsa, nesne kaldırma, metin düzenleme ve poz değişikliklerini özel bir uç nokta aracılığıyla açan Qwen-Image Edit API'yi keşfedin.

Küçük inşa edin, kotanızı izleyin ve gönderin.