Tuya, akıllı ev ekosistemini yapay zekâ tabanlı ajanlara (AI Agent) açan yeni bir ücretsiz 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 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 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.

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

---

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. Türkiye/Avrupa için geçerli data center’lar:

Önek	Bölge	REST API Base URL	WebSocket URI
EU	Orta Avrupa Data Center	https://openapi.tuyaeu.com	wss://wsmsgs.iot-eu.com
WE	Batı Avrupa Data Center	https://openapi-weaz.tuyaeu.com	wss://wsmsgs.iot-weu.com

Türkiye’de Smart Life / Tuya Smart uygulaması üzerinden açılan hesaplar bu iki data center’dan birine 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.

---

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
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 saatlik tahmin	Sıcaklık, nem, koşullar
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	Enerji tüketimi vb. metrik analizi
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. Doğal Dil ile Etkileşim (OpenClaw)

Skill’i OpenClaw platformuna ekleyip 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”

2. 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
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)

3. Komut Satırı Aracı (CLI)

Aynı tuya_api.py doğrudan terminalden de ç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

4. 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())

Öne çıkan özellikler:

• 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, kalıcı kapanışta durur
• Olay tabanlı otomasyon — TuyaAPI ile birleştirilerek olaylara göre cihaz kontrolü veya bildirim tetiklenebilir (bildirimlerde en az 30 dakikalık throttling zorunludur)

---

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

---

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

---

Desteklenmeyen İşlemler

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 ve Kısıtlar

Ortam:

• 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

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 veya Python ile yönetmenizi sağlıyor. Anahtarı tuya.ai’den almanız, önekin işaret ettiği Avrupa Base URL / WebSocket adresini (EU ya da WE) kullanmanız ve hesabınızın kayıt bölgesiyle anahtarın bölgesini eşleştirmeniz yeterli. 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.