Tuya

Tuya Son Kullanıcı API Key Nasıl Alınır ve Kullanılır?

Yazan:

Novato

On 16 Temmuz 2026

yorumlar kapalı

Tuya, akıllı ev ekosistemini yapay zekâ tabanlı ajanlara (AI Agent) ve geliştiricilere açan yeni, ücretsiz bir son kullanıcı API’si sunuyor. tuya.ai üzerinden alınan tek bir API Key ile 3.000’den fazla cihaz kategorisini ve 200’den fazla ülkedeki cihazları doğal dille ya da kodla kontrol etmek mümkün. Bu yazıda API Key’in nasıl alındığını, hangi data center’a karşılık geldiğini, üç farklı entegrasyon yöntemini ve pratikte nasıl kullanılacağını adım adım anlatıyoruz.

API Key Nasıl Alınır?

Türkiye’deki kullanıcılar ve Novato gibi Avrupa data center’ında kayıtlı hesaplar için API Key tuya.ai üzerinden alınır. Karmaşık bir imza (signature) veya çift anahtar (Access ID / Access Secret) kimlik doğrulaması gerekmez; tek bir API Key yeterlidir.

Akış oldukça basit:

tuya.ai/developer sayfasına gidin ve “Get API Key” düğmesine tıklayın.
Tuya hesabınızla (Smart Life / Tuya Smart uygulamasında kullandığınız hesap) giriş yapın.
Anahtarınız anında üretilir ve sk-… formatında gösterilir. Kopyalayıp güvenli bir yerde saklayın.
Kullanım sırasında bu anahtarı Authorization: Bearer <API_Key> başlığına koymanız yeterlidir.

Önemli: API Key formatı sk-<ÖNEK><devamı> şeklindedir. Baştaki önek, bağlanacağınız data center’ı otomatik olarak belirler. API Key’inizin bölgesi ile Tuya hesabınızın kayıt bölgesi aynı olmalıdır; aksi halde cihazlarınıza erişemezsiniz. Türkiye hesapları Avrupa data center’ına düştüğü için anahtarınız EU ya da WE önekiyle başlamalıdır.

Tuya Son Kullanıcı API Key Nasıl Alınır ve Kullanılır?

Not: Bu yeni API, geleneksel Tuya IoT Platform OpenAPI’sinden farklıdır. Eski yöntemde Access ID + Access Secret çifti ve her istek için HMAC-SHA256 imzası üretmek gerekirken; yeni 2C (end-user) API’de tek bir taşıyıcı (Bearer) anahtar tüm kimlik doğrulamayı halleder. Bu, özellikle hızlı prototipleme ve AI ajan entegrasyonları için ciddi bir sadelik kazandırır.

API Key Öneki ve Data Center Eşleşmesi

sk- ifadesinden sonraki ilk iki karakter, sizi doğru sunucuya yönlendirir. İstek atarken kullanacağınız REST API Base URL ve gerçek zamanlı olaylar için gereken WebSocket URI bu önekle belirlenir. Toplam 7 data center vardır:

Önek	Bölge	REST API Base URL	WebSocket URI
`AY`	Çin Data Center	`https://openapi.tuyacn.com`	`wss://wsmsgs.tuyacn.com`
`AZ`	ABD Batı Data Center	`https://openapi.tuyaus.com`	`wss://wsmsgs.iot-wus.com`
`EU`	Orta Avrupa Data Center	`https://openapi.tuyaeu.com`	`wss://wsmsgs.iot-eu.com`
`IN`	Hindistan Data Center	`https://openapi.tuyain.com`	`wss://wsmsgs.iot-ap.com`
`UE`	ABD Doğu Data Center	`https://openapi-ueaz.tuyaus.com`	`wss://wsmsgs.iot-eus.com`
`WE`	Batı Avrupa Data Center	`https://openapi-weaz.tuyaeu.com`	`wss://wsmsgs.iot-weu.com`
`SG`	Singapur Data Center	`https://openapi-sg.iotbing.com`	`wss://wsmsgs.iot-sea.com`

Türkiye’de Smart Life / Tuya Smart uygulaması üzerinden açılan hesaplar EU (Orta Avrupa) ya da WE (Batı Avrupa) data center’ına düşer. Kendi anahtarınızın önekine bakarak hangi Base URL’i kullanacağınızı doğrulayın; örneğin anahtarınız sk-EU... ile başlıyorsa https://openapi.tuyaeu.com adresini kullanırsınız.

Üç Entegrasyon Yöntemi

Tuya bu API’yi kullanmanın üç farklı yolunu sunuyor — hangisi iş akışınıza uyuyorsa onu seçebilirsiniz:

REST API — Standart HTTP arayüzü. Herhangi bir dilde çağrılabilir. Bearer Token kimlik doğrulama, otomatik bölge tespiti, tek tip yanıt formatı ve hazır Python SDK ile gelir.
AI Agent Skill — AI ajanları için hazırlanmış bir skill eklentisi. Claude, GPT gibi ajanlara ya da OpenClaw/ClawHub platformuna kurulur; 11 hazır workflow ile doğal dille cihaz kontrolü sağlar. MIT-0 lisanslıdır.
CLI Aracı — Resmî Node.js CLI. npm install -g tuya-smart-control-cli ile kurulur; tuya init ile hızlı kurulum, --json çıktısıyla script/CI/CD entegrasyonu sunar.

Bu üç yöntem de aynı API Key’i ve aynı endpoint’leri kullanır; yalnızca çağrı arayüzü farklıdır. Bu yazının devamında REST API ve Python SDK ağırlıklı örnekler üzerinden ilerleyeceğiz.

API Key ile Neler Yapılabilir?

Bu API, akıllı ev tarafında oldukça geniş bir kabiliyet seti sunuyor. Başlıca modüller:

Modül	Kabiliyetler	Açıklama
Ev Yönetimi	Tüm evleri ve bir evdeki odaları listeleme	Ev/oda hiyerarşisini çekme (çoklu ev, çoklu oda)
Cihaz Sorgulama	Tüm cihazlar, eve göre, odaya göre, tekil cihaz detayı	Anlık property (özellik) durumlarını da içerir
Cihaz Kontrolü	Thing Model sorgulama, property komutu gönderme	Anahtar, parlaklık, sıcaklık, mod vb.
Cihaz Yönetimi	Cihaz yeniden adlandırma	Görünen adı güncelleme
Hava Durumu	Anlık ve 7 saate kadar saatlik tahmin	Sıcaklık, nem, basınç, rüzgâr, UV indeksi
Bildirimler	SMS, sesli arama, e-posta, uygulama push’u	Yalnızca kendine gönderim (giriş yapan kullanıcıya)
Veri İstatistikleri	Saatlik istatistik yapılandırma ve veri sorgulama	SUM/MAX/MIN toplamaları, en fazla 24 saatlik pencere
IPC Bulut Yakalama	Buluttan anlık görüntü ve kısa video	Kameradan kare/video alıp oynatılabilir URL üretme
IPC Görsel Tanıma	Kamera sahne analizi	Kareyi bir AI görüntü modeline gönderip içerik tanımlama
Cihaz Mesaj Aboneliği	WebSocket ile gerçek zamanlı property değişimi ve çevrimiçi/çevrimdışı takibi	Olay tabanlı otomasyon, canlı panolar, durum uyarıları

Kullanım

1. REST API ile Doğrudan Çağrı

En yalın kullanım, standart bir HTTP istemcisiyle tek bir başlık göndermektir. Cihaz listesi çekmek için:

curl -H "Authorization: Bearer sk-EUxxxxxxxxxxxx" \
     "https://openapi.tuyaeu.com/v1.0/end-user/devices/all"

2. Doğal Dil ile Etkileşim (AI Agent Skill)

Skill’i destekleyen bir AI platformuna (OpenClaw/ClawHub ya da Claude/GPT gibi ajanlara) kurup yapılandırmada TUYA_API_KEY değerini girdikten sonra, AI Agent doğal dille komut alabilir hale gelir. Örnek ifadeler:

“Salon lambasını aç”
“Klimayı 26 dereceye ayarla”
“Bugün hava nasıl?”
“Bana bir SMS hatırlatması gönder”
“Yatak odası lambasının adını ‘başucu lambası’ yap”
“Bu ayki elektrik tüketimini göster”
“Kapı kamerasından bir görüntü al”
“Salon kamerasından 5 saniyelik video kaydet”
“Kapının önünde ne var?”
“Tüm cihaz durum değişikliklerini gerçek zamanlı izle”

3. Python SDK

Skill içinde gelen scripts/tuya_api.py dosyası, TuyaAPI sınıfını sunar. Yapılandırmayı ortam değişkenlerinden (environment variable) otomatik okur:

from tuya_api import TuyaAPI

api = TuyaAPI()  # Yapılandırmayı environment variable'lardan otomatik okur

# Tüm evleri listele
homes = api.get_homes()

# Tüm cihazları listele
devices = api.get_all_devices()

# Cihaz detayını al (anlık property durumları dahil)
detail = api.get_device_detail("cihaz_id")

# Cihazı kontrol et — lambayı aç ve parlaklığı ayarla
result = api.issue_properties("cihaz_id", {
    "switch_led": True,
    "bright_value": 500
})

# Hava durumu sorgula (İstanbul)
weather = api.get_weather(lat="41.01", lon="28.97")

# SMS bildirimi gönder
api.send_sms("Uyarı: Salon lambası çevrimdışı")

# IPC bulut yakalama — anlık görüntü al ve çözülmüş URL getir
capture = api.ipc_ai_capture_pic_allocate_and_fetch("cihaz_id")

# IPC bulut yakalama — 5 saniyelik video kaydet
video = api.ipc_ai_capture_video_allocate_and_fetch("cihaz_id", video_duration_seconds=5)

4. Node.js CLI (Resmî)

Terminalden yönetim için Tuya artık resmî bir Node.js CLI da sunuyor:

npm install -g tuya-smart-control-cli
tuya init              # API Key ile hızlı kurulum
tuya devices           # Tüm cihazları listele
tuya devices --json    # Script/CI için makine-okunur çıktı

Python tabanlı tuya_api.py de doğrudan terminalden çalıştırılabilir:

# Ev ve Cihazlar
python3 tuya_api.py homes                          # Tüm evleri listele
python3 tuya_api.py rooms <home_id>                # Bir evdeki odaları listele
python3 tuya_api.py devices                        # Tüm cihazları listele
python3 tuya_api.py device_detail <device_id>      # Cihaz detayını al

# Cihaz Kontrolü
python3 tuya_api.py model <device_id>              # Cihaz Thing Model'ini sorgula
python3 tuya_api.py control <device_id> '{"switch_led":true,"bright_value":500}'

# Cihaz Yönetimi
python3 tuya_api.py rename <device_id> "Yeni İsim"

# Hava Durumu (enlem boylam)
python3 tuya_api.py weather 41.01 28.97

# Bildirimler
python3 tuya_api.py sms "Hatırlatma mesajı"
python3 tuya_api.py voice "Sesli mesaj"
python3 tuya_api.py mail "E-posta Konusu" "E-posta içeriği"
python3 tuya_api.py push "Push Başlığı" "Push içeriği"

# Veri İstatistikleri
python3 tuya_api.py stats_data <dev_id> ele_usage SUM 2026031600 2026031623

# IPC Bulut Yakalama
python3 tuya_api.py ipc_pic_fetch <device_id> 1         # Anlık görüntü (consent=1: çözülmüş URL)
python3 tuya_api.py ipc_video_fetch <device_id> 5 1     # 5 saniyelik video

5. Gerçek Zamanlı Cihaz Mesaj Aboneliği (WebSocket)

scripts/tuya_device_mq_client.py, cihaz olaylarını gerçek zamanlı dinlemek için bir WebSocket istemcisidir. Aynı TUYA_API_KEY ile çalışır; WebSocket URI’si anahtarın önekinden otomatik belirlenir.

import asyncio
import os
from tuya_device_mq_client import TuyaDeviceMQClient

async def main():
    client = TuyaDeviceMQClient(api_key=os.environ["TUYA_API_KEY"])

    @client.on_property_change
    async def on_prop(device_id, properties):
        for prop in properties:
            t = TuyaDeviceMQClient.format_timestamp(prop["time"])
            print(f"[{t}] Cihaz {device_id}: {prop['code']} = {prop['value']}")

    @client.on_online_status
    async def on_status(device_id, status, timestamp_ms):
        t = TuyaDeviceMQClient.format_timestamp(timestamp_ms)
        print(f"[{t}] Cihaz {device_id} artık {status}")

    await client.connect()

asyncio.run(main())

Önemli — WebSocket sunucu tarafında çalışır: WebSocket istemcisi bir tarayıcıdan ya da mobil uygulamadan bağlanmamalıdır; mutlaka bir backend sunucusunda çalışmalıdır. Gerçek zamanlı veriyi bir ön yüze aktarmak için sunucu tarafında abone olup SSE, kendi WebSocket’iniz ya da polling ile iletin.

WebSocket istemcisinin öne çıkan özellikleri:

Decorator tabanlı handler kaydı — @client.on_property_change, @client.on_online_status, @client.on_raw_message
Cihaz filtreleme — yalnızca belirli cihazları izlemek için device_ids=["id1", "id2"]
Otomatik yeniden bağlanma — geçici hatalarda otomatik reconnect; 1002, 1003, 1008, 1011 gibi kalıcı kapanış kodlarında durur
Olay tabanlı otomasyon — TuyaAPI ile birleştirilerek olaylara göre cihaz kontrolü veya bildirim tetiklenebilir (bildirimlerde en az 30 dakikalık throttling zorunludur)

WebSocket mesaj formatı, iki üst düzey alan içeren JSON nesneleridir:

{
  "data": {
    "devId": "36040531cc50e35ee60d",
    "status": [
      { "code": "led_switch",   "value": true,  "time": 1773668532000 },
      { "code": "bright_value", "value": 255,   "time": 1773668532000 }
    ]
  },
  "eventType": "devicePropertyChange"
}

Gerçek Örnek: Sıcaklık Sensörü Verisi

API’nin nasıl çalıştığını somutlaştırmak için gerçek bir hesaptan çekilen verileri inceleyelim. Önce tüm cihazları listeliyoruz:

GET /v1.0/end-user/devices/all

{
  "success": true,
  "t": 1789722299740,
  "result": {
    "devices": [
      {
        "category": "wsdcg",
        "category_name": "Temperature and Humidity Sensor",
        "device_id": "bf53f9231723b0ff73149a",
        "name": "1.Nem ve Sıcaklık Sensörü",
        "online": false,
        "product_id": "4dosadbh"
      }
      // ... diğer cihazlar
    ],
    "total": 20
  }
}

Sıcaklık/nem sensörü kategorisi wsdcg, termostat kategorisi ise wk kodudur. İlgili cihazın detayına inince güncel ölçüm değerleri gelir:

GET /v1.0/end-user/devices/bf53f9231723b0ff73149a/detail

{
  "success": true,
  "result": {
    "category": "wsdcg",
    "device_id": "bf53f9231723b0ff73149a",
    "name": "1.Nem ve Sıcaklık Sensörü",
    "online": false,
    "product_name": "Temperature Sensor",
    "properties": {
      "battery_percentage": 100,
      "humidity_value": 65,
      "temp_current": 261,
      "temp_unit_convert": "c",
      "temp_alarm": "cancel",
      "hum_alarm": "cancel"
    }
  }
}

Kritik detay — sıcaklık 10× ölçeklidir: temp_current: 261 değeri 26,1 °C anlamına gelir. Tuya sıcaklık değerlerini ondalık hassasiyet için 10 ile çarpılmış tam sayı olarak saklar. Yani ham değeri 10‘a bölerek gerçek dereceyi bulursunuz. Benzer şekilde termostatın temp_set: 215 değeri 21,5 °C hedef sıcaklığına karşılık gelir. Nem (humidity_value) ise doğrudan yüzde olarak gelir ve ölçekleme gerektirmez.

Bu verileri kullanarak basit bir sıcaklık dashboard’u oluşturmak, yalnızca cihazları listeleyip wsdcg/wk kategorilerini filtrelemek ve her birinin detail endpoint’inden temp_current değerini okumaktan ibarettir.

Çevrimdışı cihazlar: Örnekte cihazın online alanı false. Zigbee sensörler genellikle uyku modunda çalıştığı ve belirli aralıklarla raporladığı için bu durum normaldir. Çevrimdışı bir cihazın properties alanı, son bilinen (önbelleğe alınmış) değerleri döndürür. Kontrol komutu göndermeden önce online durumunu kontrol etmek iyi bir pratiktir.

API Referansı (Endpoint’ler)

Tüm endpoint’ler tek tip kimlik doğrulama kullanır: Authorization: Bearer {Api-key}

Modül	İşlem	Method	Path
Ev Yönetimi	Tüm evleri listele	GET	`/v1.0/end-user/homes/all`
Ev Yönetimi	Evdeki odaları listele	GET	`/v1.0/end-user/homes/{home_id}/rooms`
Cihaz Sorgu	Tüm cihazları listele	GET	`/v1.0/end-user/devices/all`
Cihaz Sorgu	Evdeki cihazları listele	GET	`/v1.0/end-user/homes/{home_id}/devices`
Cihaz Sorgu	Odadaki cihazları listele	GET	`/v1.0/end-user/homes/room/{room_id}/devices`
Cihaz Sorgu	Tekil cihaz detayı	GET	`/v1.0/end-user/devices/{device_id}/detail`
Cihaz Kontrol	Thing Model sorgula	GET	`/v1.0/end-user/devices/{device_id}/model`
Cihaz Kontrol	Property komutu gönder	POST	`/v1.0/end-user/devices/{device_id}/shadow/properties/issue`
Cihaz Yönetimi	Cihaz yeniden adlandır	POST	`/v1.0/end-user/devices/{device_id}/attribute`
Hava Durumu	Hava durumu sorgula	GET	`/v1.0/end-user/services/weather/recent`
Bildirim	SMS gönder	POST	`/v1.0/end-user/services/sms/self-send`
Bildirim	Sesli arama	POST	`/v1.0/end-user/services/voice/self-send`
Bildirim	E-posta gönder	POST	`/v1.0/end-user/services/mail/self-send`
Bildirim	Uygulama push’u	POST	`/v1.0/end-user/services/push/self-send`
İstatistik	İstatistik yapılandırma	GET	`/v1.0/end-user/statistics/hour/config`
İstatistik	İstatistik verisi	GET	`/v1.0/end-user/statistics/hour/data`
IPC Yakalama	Bulut yakalama tahsis et	POST	`/v1.0/end-user/ipc/{device_id}/capture/allocate`
IPC Yakalama	Yakalama URL’ini çöz	POST	`/v1.0/end-user/ipc/{device_id}/capture/resolve`

Yanıt Formatı

Tüm API’ler birleşik bir yanıt yapısı kullanır. Başarılı istekte success: true ve veri result alanında; hatalı istekte success: false ile code/msg alanlarında döner.

// Başarılı
{ "success": true, "t": 1710234567890, "result": { ... } }

// Hatalı
{ "success": false, "code": 1108, "msg": "uri path invalid" }

Desteklenen Property Tipleri

Tip	Açıklama	Örnekler
`bool`	Boolean anahtar	Lamba aç/kapa, klima aç/kapa, priz aç/kapa
`enum`	Numaralandırma seçimi	Klima modu (auto/cool/heat), fan hızı (low/mid/high)
`value`	Sayısal ayar	Parlaklık (0-1000), sıcaklık (16-30)
`string`	Metin değeri	Cihaz görünen metni

Hata Kodları ve Çözümleri

API, hataları sayısal kod (1010) ya da metin tanımlayıcı ("DEVICE_NOT_EXIST_V2") olarak döndürebilir. Sık karşılaşılanlar:

Kod	Mesaj	Açıklama	Çözüm
`1010`	token invalid	API Key süresi dolmuş	Anahtarı yenileyin
`1108`	uri path invalid	Endpoint yolu hatalı	Path’i kontrol edin
`10001`	Invalid parameter	Parametre hatası	Parametre formatını doğrulayın
`10010`	End user does not exist	Hesap sorunu	Anahtarın geçerli olduğunu kontrol edin
`10011`	No bound contact	Telefon/e-posta bağlı değil	Tuya App’te iletişim bağlayın
`40000901`	Device does not exist	Cihaz bulunamadı	`device_id` değerini doğrulayın
`40000903`	Model does not exist	Cihaz modeli bulunamadı	Thing Model desteği olmayabilir
`500`	System error	Sunucu hatası	Kısa bekleyip tekrar deneyin
`429`	Too Many Requests	Hız limiti aşıldı	Üstel geri çekilme ile deneyin, `Retry-After` başlığını uygulayın

Desteklenmeyen İşlemler ve Kısıtlar

Güvenlik açısından hassas veya karmaşık veri tipleri içeren aşağıdaki işlemler desteklenmez — bunlar için doğrudan Tuya uygulamasını kullanmak gerekir:

Kilit kontrolü — Kapı açma, akıllı kilitleri kilitleme/açma (güvenlik hassasiyeti)
Canlı video akışı — Gerçek zamanlı stream çekme (bulut anlık görüntü/kısa video desteklenir)
Görüntü işlemleri — Cihaz görüntülerini yükleme/indirme
Karmaşık veri tipi kontrolü — raw, bitmap, struct veya array typeSpec’li property’ler
Firmware yükseltmesi — OTA firmware güncellemeleri
Cihaz ekleme/kaldırma — Yeni cihaz eşleştirme veya mevcut cihazı silme

Ön Gereksinimler

Python 3.7+
requests kütüphanesi (pip install requests)
websockets kütüphanesi (pip install websockets) — gerçek zamanlı mesaj aboneliği için
Node.js CLI için: npm install -g tuya-smart-control-cli

Deneme (Trial) aşaması: Şu an sunulan tüm API endpoint’leri deneme aşamasındadır. Her endpoint için hız limiti (rate limit), çağrı kotası ve diğer kullanım kısıtları geçerlidir. Limit hatası veya kota hatası aldığınızda kısa bir bekleme sonrası yeniden deneyin.

Özet

Tuya’nın tuya.ai üzerinden verdiği API Key, tek bir anahtarla akıllı ev cihazlarını sorgulama, kontrol etme, bildirim gönderme, enerji istatistiği çekme ve kamera görüntüsü yakalamaya kadar geniş bir yelpazeyi doğal dil, Python ya da Node.js CLI ile yönetmenizi sağlıyor. Anahtarı tuya.ai’den almanız, önekin işaret ettiği data center Base URL / WebSocket adresini kullanmanız ve hesabınızın kayıt bölgesiyle anahtarın bölgesini eşleştirmeniz yeterli. Sıcaklık gibi ölçüm verilerinde 10× ölçekleme gibi birkaç inceliğe dikkat ettiğinizde, kilit kontrolü ve canlı stream gibi hassas işlemler dışında akıllı ev otomasyonunun büyük bölümü bu API ile programlanabilir hale geliyor.