Viona Developer API 3.0 · Python SDKDokümantasyon · API key oluştur
Adım adım entegrasyon

API key'den çalışan Viona AI 3 chatbot'a

Bu rehber VionaAI Python SDK 3.0'ı güvenli biçimde kurup backend projesine bağlamak için gerekli temel akışı tek sayfada toplar.

1. API key oluştur

Viona Developer panelini aç

dev.vionaai.site/#keys adresindeki API key alanına git.

Yeni anahtar oluştur

Oluşturulan viona_live_... anahtarını güvenli bir yerde sakla. Anahtarı herkese açık repo veya frontend kaynaklarına ekleme.

Gerekirse origin kısıtla

Tarayıcı tabanlı mimaride izin verilen originleri panelden sınırlandırabilirsin. Sunucu tarafında mimarini origin davranışına göre planla.

Önemli: Web sitesi frontend'inde doğrudan Viona API key kullanmak yerine kendi backend endpoint'ini oluştur. Kullanıcı tarayıcısı yalnızca senin backend'ine bağlansın.

2. Paketi kur

python -m pip install -U vionaai

3.0.0 sürümünü sabitlemek istersen:

python -m pip install vionaai==3.0.0

3. API key'i ortam değişkeninde sakla

Windows PowerShell

$env:VIONA_API_KEY="viona_live_YENI_API_KEYIN"

Windows CMD

set VIONA_API_KEY=viona_live_YENI_API_KEYIN

Linux / macOS

export VIONA_API_KEY="viona_live_YENI_API_KEYIN"

SDK ortam değişkeninden key okuyabildiği için daha sonra doğrudan Vionaai() başlatabilirsin.

4. İlk isteği gönder

from Viona.api import Vionaai

with Vionaai() as client:
    print(client.sor("Merhaba Viona!"))

SDK varsayılan olarak POST https://dev.vionaai.site/api/v1/chat endpointini ve viona-ti-3.0 modelini kullanır.

5. Async kullanım

FastAPI, bot veya eşzamanlı çoklu görevlerde async yardımcılarını kullanabilirsin.

import asyncio
from Viona.api import Vionaai, Models

async def main():
    async with Vionaai() as client:
        cevap = await client.sor_async(
            "Async programlama nedir?",
            model=Models.TI_3_0,
        )
        print(cevap)

asyncio.run(main())

6. Güvenli web chatbot mimarisi

İdeal akış: Tarayıcı → senin backend'in → Viona Developer API. Böylece API key kullanıcıya ulaşmaz.

Flask backend örneği
import os
from flask import Flask, jsonify, request
from Viona.api import Vionaai
from Viona.exceptions import VionaError

app = Flask(__name__)
client = Vionaai(api_key=os.environ["VIONA_API_KEY"])

@app.post("/api/chat")
def chat():
    body = request.get_json(silent=True) or {}
    message = str(body.get("message", "")).strip()
    if not message:
        return jsonify({"error": "message gerekli"}), 400

    try:
        return jsonify({"answer": client.sor(message)})
    except VionaError as exc:
        return jsonify({
            "error": exc.error_type or "viona_error",
            "message": exc.message,
        }), exc.status_code or 500

7. Kredi ve istek bilgilerini izle

with Vionaai() as client:
    print(client.sor("Merhaba"))
    print("İstek maliyeti:", client.credit_cost)
    print("Kalan kredi:", client.credit_balance)
    print("Request ID:", client.request_id)
    print("Rate limit:", client.rate_limit_remaining)

Developer dokümantasyonundaki kredi sistemi başarılı isteklerde ortak dev_kredi bakiyesini kullanır. Kredi başlıklarını SDK yardımcı alanlarından okuyabilirsin.

8. Hata yönetimi

HTTPSDK ExceptionAPI türü
400InvalidRequestErrorinvalid_request_error
401AuthenticationErrorauthentication_error
402InsufficientCreditErrorinsufficient_credit
403OriginNotAllowedErrororigin_not_allowed
413RequestTooLargeErrorrequest_too_large
422InvalidModelErrorinvalid_model
429RateLimitErrorrate_limit_exceeded
502UpstreamUnavailableErrorupstream_unavailable
503ServiceUnavailableErrorservice_unavailable

SDK geçici bağlantı/timeout ve 429, 502, 503 gibi durumlarda yapılandırılmış retry mekanizması uygulayabilir.

Daha fazla ayrıntı

Endpoint, authentication, parametre, kredi ve hata yapısının tamamı için Viona Developer dokümantasyonunu kullan.