VionaAI Python SDK 3.0

VionaAI Python SDK, Orvix Games tarafından geliştirilen Viona Developer API 3.0 için resmi Python istemcisidir. Viona AI modellerini backend, bot, otomasyon, masaüstü uygulaması ve sunucu projelerine bağlamak için hazırlanmıştır.

• API Base URL: https://dev.vionaai.site/api/v1
• Dokümantasyon: https://dev.vionaai.site/docs/
• API key oluştur: https://dev.vionaai.site/#keys
• SDK sürümü: 3.0.0
• Varsayılan model: viona-ti-3.0

API anahtarınızı frontend JavaScript'e, mobil uygulama kaynaklarına veya herkese açık depolara gömmeyin. Üretimde anahtarı sunucu tarafında ve ortam değişkeninde saklayın.

---

Kurulum

PyPI üzerinden:

python -m pip install -U vionaai

Belirli sürüm:

python -m pip install vionaai==3.0.0

Wheel dosyasından:

python -m pip install vionaai-3.0.0-py3-none-any.whl

Kurulumu kontrol et:

python -c "from Viona.api import Vionaai; print(Vionaai.SDK_VERSION)"

---

Önerilen import

Yeni projelerde önerilen kullanım:

from Viona.api import Vionaai

Model sabitleriyle birlikte:

from Viona.api import Vionaai, Models

Hata sınıfları:

from Viona.api import Vionaai
from Viona.exceptions import VionaError, AuthenticationError, InsufficientCreditError

Kısa import da desteklenir:

from Viona import Vionaai, Models

Python'da import Vionaai from Viona.api geçerli bir sözdizimi değildir. Doğru kullanım from Viona.api import Vionaai biçimindedir.

Eski kodları kırmamak için Viona ve VionaAI isimleri geriye uyumluluk alias'ı olarak tutulmuştur, ancak yeni projelerde Vionaai kullanılması önerilir.

---

API key alma

API anahtarını Viona Developer panelinden oluştur:

https://dev.vionaai.site/#keys

Önerilen yöntem anahtarı ortam değişkeninde saklamaktır.

Windows PowerShell

$env:VIONA_API_KEY="viona_live_YENI_API_KEYIN"

Kalıcı kullanıcı değişkeni:

setx 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"

Python tarafında:

from Viona.api import Vionaai

client = Vionaai()

İstersen anahtarı doğrudan da verebilirsin:

from Viona.api import Vionaai

client = Vionaai(api_key="viona_live_YENI_API_KEYIN")

---

30 saniyelik başlangıç

from Viona.api import Vionaai

client = Vionaai(api_key="viona_live_YENI_API_KEYIN")

cevap = client.sor("Viona API hakkında kısa bir tanıtım yaz.")
print(cevap)

client.close()

Context manager kullanımı daha temizdir:

from Viona.api import Vionaai

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

SDK varsayılan olarak şu endpointi kullanır:

POST https://dev.vionaai.site/api/v1/chat

ve Bearer authentication gönderir:

Authorization: Bearer viona_live_YENI_API_KEYIN

---

Chat completion

Tam API yanıtını almak için chat() kullan:

from Viona.api import Vionaai, Models

with Vionaai(api_key="viona_live_YENI_API_KEYIN") as client:
    response = client.chat(
        messages=[
            {"role": "system", "content": "Kısa ve net cevap ver."},
            {"role": "user", "content": "REST API nedir?"},
        ],
        model=Models.TI_3_0,
        temperature=0.7,
        max_tokens=1024,
    )

    print(response["choices"][0]["message"]["content"])

Parametreler

Alan	Tür	Varsayılan	Açıklama
messages	list	zorunlu	system, user, assistant mesaj dizisi
model	str	viona-ti-3.0	Kullanılacak model
temperature	float	0.7	0 ile 2 arasında üretim çeşitliliği
max_tokens	int	1024	64 ile 8192 arasında yanıt sınırı

---

Sadece cevap metnini alma

from Viona.api import Vionaai

client = Vionaai(api_key="viona_live_YENI_API_KEYIN")

text = client.chat_text([
    {"role": "user", "content": "Bana kısa bir oyun fikri üret."}
])

print(text)
client.close()

Daha kısa kullanım:

from Viona.api import Vionaai

client = Vionaai(api_key="viona_live_YENI_API_KEYIN")
print(client.sor("Python nedir?"))
client.close()

İngilizce alias:

print(client.ask("Explain Python decorators briefly."))

---

Çok turlu sohbet

Konuşma geçmişini messages dizisinde tut:

from Viona.api import Vionaai

messages = [
    {"role": "system", "content": "Yardımcı bir yazılım asistanısın."},
    {"role": "user", "content": "Python ile HTTP sunucusu nasıl açılır?"},
]

with Vionaai() as client:
    first = client.chat(messages)
    first_text = first["choices"][0]["message"]["content"]
    print(first_text)

    messages.append({"role": "assistant", "content": first_text})
    messages.append({"role": "user", "content": "8080 portunda çalıştır."})

    second = client.chat(messages)
    print(second["choices"][0]["message"]["content"])

---

Modeller

Viona Developer API 3.0 model kimlikleri:

Model	Kullanım
viona-ti-3.0	Genel amaçlı akıl yürütme, analiz ve üretken görevler
viona-mythrion	Yaratıcı üretim, strateji ve uzun içerik
viona-chat-1.5	Hızlı ve doğal çok turlu sohbet
viona-codix-1.6	Kod, hata ayıklama, mimari ve teknik dokümantasyon

Sabitlerle kullanım:

from Viona.api import Vionaai, Models

client = Vionaai(
    api_key="viona_live_YENI_API_KEYIN",
    model=Models.CODIX_1_6,
)

print(client.sor("Bu Python kodunu optimize et."))
client.close()

Tüm sabitler:

print(Models.all())

Canlı model kataloğu:

from Viona.api import Vionaai

with Vionaai() as client:
    print(client.models())

Bu çağrı:

GET https://dev.vionaai.site/api/v1/models

endpointini kullanır.

---

Async kullanım

FastAPI, botlar ve eşzamanlı işler için async metotlar bulunur.

import asyncio
from Viona.api import Vionaai, Models


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


asyncio.run(main())

Tam async yanıt:

response = await client.chat_async([
    {"role": "user", "content": "Merhaba"}
])

Sadece metin:

text = await client.chat_text_async([
    {"role": "user", "content": "Merhaba"}
])

İngilizce helper:

text = await client.ask_async("Hello Viona")

---

Kimlik doğrulama seçenekleri

Varsayılan ve önerilen yöntem Bearer authentication'dır:

from Viona.api import Vionaai

client = Vionaai(
    api_key="viona_live_YENI_API_KEYIN",
    auth_mode="bearer",
)

Alternatif X-API-Key başlığı:

client = Vionaai(
    api_key="viona_live_YENI_API_KEYIN",
    auth_mode="x-api-key",
)

---

Origin kısıtlaması

API key üzerinde origin kısıtlaması kullanıyorsan gerektiğinde origin gönderilebilir:

from Viona.api import Vionaai

client = Vionaai(
    api_key="viona_live_YENI_API_KEYIN",
    origin="https://ornek.com",
)

Origin izinlerini Viona Developer panelinden yapılandır.

---

Kredi bilgileri

Dokümantasyona göre başarılı istekler ortak dev_kredi bakiyesinden düşer. Son HTTP yanıtının kredi başlıklarına SDK üzerinden erişebilirsin:

from Viona.api import Vionaai

with Vionaai() as client:
    print(client.sor("Merhaba"))
    print("İstek maliyeti:", client.credit_cost)
    print("Kalan kredi:", client.credit_balance)

Desteklenen yardımcı alanlar:

print(client.credit_cost)
print(client.credit_balance)
print(client.request_id)
print(client.rate_limit_remaining)
print(client.last_status_code)

---

Hata yönetimi

from Viona.api import Vionaai
from Viona.exceptions import (
    AuthenticationError,
    InsufficientCreditError,
    OriginNotAllowedError,
    RateLimitError,
    VionaError,
)

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

except AuthenticationError:
    print("API key eksik veya geçersiz.")

except InsufficientCreditError:
    print("dev_kredi bakiyesi yetersiz.")

except OriginNotAllowedError:
    print("Bu origin API key için izinli değil.")

except RateLimitError:
    print("İstek hız sınırı aşıldı.")

except VionaError as exc:
    print("Viona API hatası:", exc)
    print("HTTP:", exc.status_code)
    print("Tür:", exc.error_type)
    print("Request ID:", exc.request_id)

HTTP hata eşlemesi

HTTP	Exception	API hata türü
400	InvalidRequestError	invalid_request_error
401	AuthenticationError	authentication_error
402	InsufficientCreditError	insufficient_credit
403	OriginNotAllowedError	origin_not_allowed
413	RequestTooLargeError	request_too_large
422	InvalidModelError	invalid_model
429	RateLimitError	rate_limit_exceeded
502	UpstreamUnavailableError	upstream_unavailable
503	ServiceUnavailableError	service_unavailable

Ağ ve timeout hataları:

from Viona.exceptions import APIConnectionError, APITimeoutError

SDK 429, 502, 503, timeout ve geçici bağlantı hatalarında yapılandırılmış retry uygular.

---

Retry ve timeout

from Viona.api import Vionaai

client = Vionaai(
    timeout=45,
    max_retries=3,
    retry_delay=1.0,
)

Retry-After saniye başlığı varsa SDK onu kullanır; yoksa exponential backoff uygular.

---

Flask entegrasyonu

API key'i tarayıcıya vermek yerine kendi backend endpointinden Viona'ya bağlan:

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():
    data = request.get_json(silent=True) or {}
    message = str(data.get("message", "")).strip()

    if not message:
        return jsonify({"error": "message gerekli"}), 400

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


if __name__ == "__main__":
    app.run(debug=True)

Frontend artık yalnızca kendi /api/chat endpointine istek gönderir; Viona API key backend'de kalır.

---

FastAPI entegrasyonu

import os
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from Viona.api import Vionaai
from Viona.exceptions import VionaError

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


class ChatBody(BaseModel):
    message: str


@app.post("/api/chat")
async def chat(body: ChatBody):
    try:
        answer = await client.sor_async(body.message)
        return {"answer": answer}
    except VionaError as exc:
        raise HTTPException(
            status_code=exc.status_code or 500,
            detail=exc.message,
        )


@app.on_event("shutdown")
async def shutdown_event():
    await client.aclose()

---

CLI

Paket kurulduktan sonra:

vionaai --help

Tek mesaj:

vionaai ask "Viona API nedir?"

Model seç:

vionaai ask "Python kodu yaz" --model viona-codix-1.6

Ham JSON yanıtı:

vionaai ask "Merhaba" --json

Model listesi:

vionaai models

SDK bilgisi:

vionaai info

Geriye uyumluluk için viona CLI adı da aynı komuta yönlendirilmiştir.

---

Client bilgisi

API key'i göstermeden yapılandırmayı görebilirsin:

from Viona.api import Vionaai

client = Vionaai()
print(client.bilgi())
client.close()

Örnek yapı:

{
    "sdk_version": "3.0.0",
    "api_version": "v1",
    "base_url": "https://dev.vionaai.site/api/v1",
    "default_model": "viona-ti-3.0",
    "timeout": 30.0,
    "max_retries": 2,
    "auth_mode": "bearer",
    "origin": None,
}

---

Viona 3.0 API yapısı

Chat

POST /api/v1/chat

Örnek gövde:

{
  "model": "viona-ti-3.0",
  "messages": [
    {"role": "user", "content": "Merhaba"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}

Models

GET /api/v1/models

Tüm endpoint, authentication, kredi ve hata ayrıntıları için resmi dokümantasyon:

https://dev.vionaai.site/docs/

---

Eski importtan geçiş

Eski kullanım:

from Viona import Viona

client = Viona()

Yeni önerilen kullanım:

from Viona.api import Vionaai

client = Vionaai()

Geriye uyumluluk alias'ları nedeniyle eski Viona sınıf adı 3.0.0'da çalışmaya devam eder.

---

PyPI'de farklı hesaptan yayınlama

Bu dağıtımın PyPI proje adı artık:

vionaai

Bu, eski viona dağıtımından bağımsız bir PyPI projesidir.

Build:

python -m pip install -U build twine
python -m build

Kontrol:

python -m twine check --strict dist/*

Yayın:

python -m twine upload -u __token__ dist/*

Yayınlandıktan sonra kurulum:

pip install vionaai

Import adı ise:

from Viona.api import Vionaai

PyPI proje adı ile Python import paketi aynı olmak zorunda değildir. Bu projede dağıtım adı vionaai, import namespace'i Viona olarak tasarlanmıştır.

---

Güvenlik önerileri

• API key'i kaynak koda gömme.
• .env veya sunucu secret sistemi kullan.
• .env dosyasını Git'e ekleme.
• Sızıntı şüphesinde API key'i yenile veya iptal et.
• Tarayıcıdan doğrudan Viona API'ye bağlanmak yerine backend proxy kullan.
• Origin kısıtlamasını mimarine uygun yapılandır.
• 429, 502, 503 hatalarını uygulama seviyesinde kullanıcıya düzgün göster.

---

Bağlantılar

• Developer Panel: https://dev.vionaai.site/
• API Dokümantasyonu: https://dev.vionaai.site/docs/
• API Key Oluştur: https://dev.vionaai.site/#keys

---

Lisans

MIT License. Ayrıntılar için LICENSE dosyasına bakın.

© 2026 Viona AI · Orvix Games