API referansı

Her kayıt id (model olarak gönderdiğin değer), label, kind (image ya da video), family ve developer taşır — modeli geliştiren şirket (Vellria adıyla sunulan modelde null) — ayrıca iki kip taşır, text ve reference: yalnız prompt gönderirsen model text kipinde çalışır — text-to-image ya da text-to-video çağrısı; aynı id'ye bir ya da daha fazla referans görsel eklersen model bunun yerine reference kipinde çalışır — image-to-image ya da image-to-video — ikisi arasında seçecek ayrı bir id yoktur. Her kip kendi sizes'ını (görsel) ya da resolutions'ını (video), bir default'ı, max_prompt_length'i (bu kipin prompt için, ve kendi sınırını ilan etmeyen her serbest metin parametresi için uyguladığı karakter sınırı) ve parameters'ı taşır. Her boyut ya da çözünürlük, etiketinin yanında ratio ve tier taşır, yani en-boy oranını ya da çözünürlük kademesini öğrenmek için etiketi ayrıştırman gerekmez (ratio adaptive ise çıktı oranını girdi görselinden alır). reference_images text kipinde null'dır; reference kipinde o kipin kabul ettiği referans görsel min ve max sayısını, ilkinden sonraki her referans için alınan extra_credits'i ve bir referans görselin uyması gereken dosya sınırlarını taşır. Referans yuvalarının rolü sabit olan bir model bu rolleri sırayla reference_images.roles altında listeler (bugün her modelde null): image_urls içindeki ilk adres ilk rolü alırdı, sonraki her adres bir sonrakini alırdı, son rol kalanlar için tekrarlanırdı.

Seçilen boyutun kredisi üretim başlarken düşülür, başarısız olursa kendiliğinden iade edilir. Her modelin boyutları, referans sınırları, parametreleri ve fiyatları GET /v1/models ucundan gelir.

Fiyatı aynı modelin görselden videoya fiyatıdır, referans başına ek ücret yoktur. Hatalar, hepsi HTTP 400 ve kredi düşmeden önce: değer frame ya da subject değilse veya modelin subject kipi yoksa invalid_reference_mode; subject kipinde referans yoksa ya da modelin kabul ettiğinden fazlaysa invalid_image_urls; istem karşılığı olmayan bir @image anıyorsa (örneğin iki görselle @image3) invalid_reference_token. frame kipinde @image1 düz metindir.

1M token başına: giriş 50 kredi ($0,50) · önbellekten giriş 5 kredi ($0,05) · çıkış 200 kredi ($2,00).

• Yanıtlar filtresizdir: Vellria bu uca içerik denetimi eklemez; kendi son kullanıcılarınızı denetlemek sizin sorumluluğunuzdadır. Mesajlarınızın önüne tek satırlık bir kimlik talimatı eklenir; token'ları ücretlendirilmez ve usage'a sayılmaz.
• Görseller: user mesajına image_url parçaları ekleyin; mesaj başına en çok 4, istek başına en çok 8. Görseli önce POST /v1/uploads ile yükleyin ve dönen adresi verin; data URL data_url_not_supported ile reddedilir.
• max_tokens varsayılan olarak 1024, en çok 4096. Akıl yürütme (reasoning, thinking) alanları yok sayılır ve yanıtlar hiçbir zaman akıl yürütme içermez.
• stream: true ile yanıt OpenAI parça biçiminde sunucu olayları (data: satırları) olarak gelir ve data: [DONE] ile biter. Ondan önceki parçanın choices alanı boştur; usage ve ücreti taşır. Akış başladıktan sonraki hata data: {"error": …} olayı olarak gelir; metin gönderilmişse o metin ücretlenir (usage parçası hatadan hemen önce gelir), yoksa ücret alınmaz.
• Her yanıt OpenAI usage alanının yanında credits_charged (kesirli kredi), cost_usd ve credits_debited (bakiyeden şimdi düşen tam kredi; kesirler hesabınızda birikir) taşır. Reddedilen, başarısız ya da boş yanıt ücretlendirilmez; iptal ettiğiniz akış o ana kadar üretilen token kadar ücretlendirilir.
• İstek başlamadan bakiye olası en uzun yanıtı karşılamalıdır (yoksa 402 insufficient_credits). Dakikadaki istek sayısı ve aynı anda süren istekler hesap başına sınırlıdır (429 rate_limit_exceeded).

import OpenAI from "openai"

const client = new OpenAI({
  apiKey: "vll_...",
  baseURL: "https://vellria.com/v1",
})

const stream = await client.chat.completions.create({
  model: "vellria-uncensored-chat",
  messages: [{ role: "user", content: "Bir hikâyeye başlayalım." }],
  stream: true,
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
}

Referans olarak kullanılan görsel en fazla 20 MB'lık durağan bir JPEG, PNG, GIF ya da WebP olmalı, saydam alan taşımamalı ve seçilen modelin ilan ettiği dosya sınırları içinde olmalıdır: `GET /v1/models` bunları model başına `reference_images.limits` altında döner (bayt, piksel cinsinden kenar ve megapiksel). Sınırların dışındaki bir referans, hiç kredi harcanmadan HTTP 400 ve `image_unreadable` ile reddedilir; sebep `too_small` ya da `too_large` olur. EXIF gibi üst veri dosya saklanırken silinir. Adres tahmin edilemez bir kimlik taşır ve hiçbir üretimde kullanılmazsa yüklemeden 24 saat sonra silinir (yanıttaki expires_at alanı); bir üretimde referans olarak kullanıldıysa yüklemeden sonra 48 saat saklanır, üretilen dosyalardan çok daha kısa; süresi dolduğunda uç HTTP 410 ve content_expired döner. Bir üretimin kendi dosya adresi (/v1/generations/{id}/file) kimlik doğrulaması ister ve referans olarak kullanılamaz: üretim uçları onu kredi düşmeden HTTP 400 ve reference_not_public koduyla reddeder. Bunun yerine dosyayı bu uca yükle ya da bir görsel üretimini POST /v1/generations/{id}/reference ile herkese açık bir referans adresine çevir. Referans görseller içerik taramasından geçmez: hiçbir görsel, gösterdiği kişi ya da içerik yüzünden reddedilmez; bu yolda image_blocked reti yoktur. Biz referansı yalnız dosyanın kendisi okunamadığında reddederiz: okunamayan görsel HTTP 400 ve image_unreadable döner; sebep buysa reason animated, transparent too_small ya da too_large taşır. Modelin kendisi işleyemediği bir referans görseli yine de reddedebilir; o üretim error_code reference_rejected ile başarısız olur ve kredisi otomatik iade edilir. Referans hazırlanmazsa istek HTTP 503 ve reference_unavailable döner, kredi düşülmez. API anahtarıyla gönderilen prompt modele gönderildiği gibi gider; yalnız reşit olmayanların cinsel istismarını içeren istekler HTTP 400 ve content_blocked koduyla reddedilir. Her referans önce bir yükleme olarak saklanır (dış adresle verilen görsel üst verisi silinerek kopyalanır) ve sağlayıcı aynı sabitlenmiş adresi çeker; yani sağlayıcıya tam olarak saklanan dosya gider.

GET /v1/generations listesi yalnız tamamlanmış ve süren üretimleri gösterir: başarısız üretim listede ve total sayısında yer almaz, GET /v1/generations/{id} ise onu 30 gün error_code ile döndürmeye devam eder; sonra başarısız kayıt silinir ve GET /v1/generations/{id} ile dosya ucu HTTP 404 ve not_found kodu döner. Listeyi ?status=failed ile süzmek 400 döner; başarısız üretim GET /v1/billing/history yanıtının üretim yarısında (generations_total dahil) da yer almaz. Henüz bildirilmemiş başarısızlıkları GET /v1/generations/failures listeler: count, refunded_cents (gerçekten iade edilen kredi, iade yapılmadıysa 0), until ve data'da en yeni en çok 5 kayıt. POST /v1/generations/failures/seen ile görüldü işaretlenir: ya ids (1-50 üretim kimliği) ya da until (o ana kadarki bütün başarısızlıklar) gönderilir; başka hesabın kimlikleri yok sayılır ve bir başarısızlık hangi cihazda olursa olsun yalnız bir kez bildirilir.

Bu değerleri kendi tarafına sabit yazma, uçtan oku. POST /v1/billing/create-checkout ya bu listeden bir package_id ya da 30 ile 10000 USD arasında, sente yuvarlanan serbest bir price_amount alır; serbest tutar paketlerle aynı düz oranla krediye çevrilir. İkisi birlikte gelirse package_id kazanır ve fiyatla kredi katalogdan okunur. Tanınmayan package_id HTTP 400 ile invalid_package, aralık dışındaki tutar invalid_amount kodunu döner. Aynı anda en çok beş açık ödeme olabilir; fazlası, biri ödenene, iptal edilene ya da süresi dolana kadar HTTP 429 döner. Yanıt checkout_url taşıyan ödeme kaydıdır: ödeyeni oraya gönder, ödemeyi ödeme ortağımızın güvenli sayfasında USD olarak kartla (Visa ya da Mastercard) yapsın. Ödeme onaylandığında kredi kendiliğinden yazılır; durumu GET /v1/billing/payments/{id} ile yoklayabilirsin. POST /v1/billing/payments/{id}/cancel açık bir ödemeyi iptal edildi olarak işaretler; ödeme yine de tamamlanırsa kredi yazılır. İsteğe bağlı provider alanı ödemeyi alacak sağlayıcıyı seçer; kabul edilen değerler whop (kart), nowpayments (kripto) ve telegram_stars (Telegram Yıldızı). GET /v1/billing/packages checkout'a açık sağlayıcıları providers içinde listeler ve alan gönderilmezse listenin ilki kullanılır. Tanınmayan ya da kapalı sağlayıcı HTTP 400 ve invalid_provider kodu döner; boş providers listesi ödemenin şu anda kapalı olduğu anlamına gelir. Her paket ayrıca onu alamayan sağlayıcıları excluded_providers içinde listeler; örneğin paket Telegram Yıldızı fatura sınırının üstündeyse telegram_stars. O paket için dışlanmış bir sağlayıcıyla açılan checkout HTTP 400 ve package_unavailable_for_provider kodu döner, ödeme açılmaz. GET /v1/billing/balance harcanabilir toplamı credits alanında döner ve onu kovalara ayırır: süresi dolmayan permanent_credits, subscription_expires_at anında (milisaniye cinsinden zaman damgası; etkin abonelik kredisi yoksa null) yanan subscription_credits ve gift_expires_at anında (etkin hediye yoksa null) yanan, kayıtta bir kez verilen hediye kredisi gift_credits; harcama önce hediye kredisinden, sonra abonelik kredisinden, en son kalıcı krediden yapılır. Aylık abonelik planları GET /v1/billing/packages yanıtında ayrı bir plans listesinde gelir; her planın bir id'si, bir adı, aylık usd fiyatı ve her dönem yazdığı kredisi vardır. POST /v1/billing/subscribe bu listeden bir plan_id alır ve bekleyen aboneliği, ödeyeni göndereceğiniz checkout_url ile birlikte döner. Abonelik yalnız kartla ödenir: whop dışındaki bir provider HTTP 400 ve invalid_provider kodu döner, bilinmeyen plan_id ise invalid_plan döner. Ödenen her dönem kalan abonelik kredisini planın tam miktarıyla değiştirir; kullanılmayan abonelik kredisi sonraki aya devretmez, kalıcı krediye dokunulmaz. Zaten sahip olduğunuz plana yeniden abone olmak HTTP 409 ve already_subscribed döner. Daha büyük plana geçiş hemen başlar ve mevcut planın kalan kredisi yeni döneme eklenir; daha küçük plana geçiş HTTP 409 ve downgrade_requires_cancel döner. GET /v1/billing/subscription etkin aboneliği subscription alanında (plan_id, status, current_period_end ve cancel_at_period_end), açık bir ödeme sayfasını pending alanında döner; olmayan alan null'dır. Aynı anda tek bir ödeme sayfası açık olabilir: aynı plana yeniden abone olmak açık sayfayı döner, başka bir plan seçmek önce açık olanı kapatır, hâlâ açılmakta olan bir sayfa varken HTTP 409 ve checkout_in_progress döner. POST /v1/billing/subscription/cancel yenilemeyi mevcut dönemin sonunda durdurur: abonelik kredisi current_period_end'e kadar kullanılabilir kalır ve iade yapılmaz. Yanıt cancel_at_period_end değeri true olan aboneliktir (yeniden çağırmak aynısını döner); etkin abonelik yoksa HTTP 404 ve subscription_not_found, iptal doğrulanamadıysa HTTP 502 ve subscription_cancel_failed döner; bu durumda yeniden deneyin. plans içindeki her plan ayrıca bir rank taşır: rank'ı büyük olan plan küçük olana göre yükseltmedir; yönü fiyattan değil rank'tan okuyun. GET /v1/billing/history abonelik ödemelerini ayrıca subscription_payments içinde listeler (type subscription, payment_id, subscription_id, plan_id, amount_usd, status paid, refunded ya da mismatch, period_end ve created_at); bu liste subscription_payments_offset ile kendi başına sayfalanır, toplamı subscription_payments_total'dadır.

GET /v1/generations yanıtı retention_days alanını, her üretim de expires_at alanını taşır; süresi dolmuş bir dosya istendiğinde HTTP 410 ve content_expired kodu döner. Daha uzun tutman gereken her şeyi indir. Bir üretimi kendin de silebilirsin: DELETE /v1/generations/{id} saklanan dosyayı hemen kaldırır ve purged_at döner. Silinen üretim API'den çıkar: GET /v1/generations listesinde görünmez; GET /v1/generations/{id}, dosya ucu ve ikinci bir DELETE, hiç var olmamış bir kimlikte olduğu gibi HTTP 404 ve not_found kodu döner. Harcanan kredi iade edilmez ve GET /v1/billing/history içinde kalır. Başarısız üretimin kaydı 30 gün sonra silinir; ondan sonra GET /v1/generations/{id} ve dosya ucu HTTP 404 döner. Hâlâ queued ya da processing durumundaki bir üretim henüz silinemez ve HTTP 409 ile generation_in_progress kodunu döner.

Ödeme kayıtları fatura kaydı olarak saklanır, yani kapatılmış bir hesap tutmakla yükümlü olduğumuz ödeme geçmişinde görünmeye devam eder. Uç yalnız oturumla kimlik doğrular: konsoldaki Hesap sayfasından çağrılır ve API anahtarı taşıyan istek HTTP 403 ile reddedilir. Ödemesi henüz kesinleşmemiş bir hesap kapatılamaz, HTTP 409 ile pending_payment kodunu döner, çünkü o ödemenin kredisi hâlâ yazılabilir; hesap başka bir hesaba bağlanırken de aynı 409 merge_in_progress ile döner. İki durumda da biraz bekleyip yeniden dene.