REST · v1

API dokümantasyonu

Nuvio'daki tüm üretim modlarını — görsel, video, ses ve metin — kendi uygulamandan tek bir REST API ile kullan. Aynı yetenekler MCP sunucusu üzerinden yapay zekâ asistanlarına da açık.

Genel bakış Kimlik doğrulama Hızlı başlangıç Uç noktalar Modeller ve ayarlar Webhook'lar Hatalar Hız limitleri MCP

Genel bakış

Test modu: API henüz yayında değil. Bu sayfa sözleşme taslağıdır; adresler ve yanıtlar değişebilir.

Base URL

https://api.nuvio.app/v1

API anahtarı alBir dakikada oluşturStüdyo'da deneKod yazmadan üret

Kimlik doğrulama

Her istekte API anahtarını Authorization başlığında Bearer token olarak gönder. Anahtarlar nv_live_ ile başlar.

HTTP

Authorization: Bearer nv_live_••••••••••••••••

Anahtarı yalnız sunucu tarafında kullan; tarayıcı koduna ya da mobil uygulamaya gömme.
Ortam değişkeninde sakla (ör. NUVIO_API_KEY) ve sürüm kontrolüne ekleme.
İzinler: “Üretim başlat” kredi harcayan istekler, “Okuma” durum ve listeleme içindir.
Sızdığından şüphelendiğin anahtarı API anahtarları sayfasından hemen iptal et.

Hızlı başlangıç

Anahtarını ortam değişkenine koy

Shell

export NUVIO_API_KEY="nv_live_…"

Bir üretim başlat

curl -X POST https://api.nuvio.app/v1/generations \
  -H "Authorization: Bearer $NUVIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "aurora-2",
    "prompt": "Mountain lake on a misty morning, cinematic light",
    "settings": {
      "aspect_ratio": "16:9",
      "count": 2
    }
  }'

Bitene kadar durumu sorgula

async function waitFor(id) {
  while (true) {
    const res = await fetch(`https://api.nuvio.app/v1/generations/${id}`, {
      headers: { Authorization: `Bearer ${process.env.NUVIO_API_KEY}` },
    });
    const gen = await res.json();
    if (gen.status === "succeeded") return gen.outputs;
    if (gen.status === "failed") throw new Error(gen.error.message);
    await new Promise((r) => setTimeout(r, 2000));
  }
}

Üretimde sorgulamak yerine webhook kullanmanı öneririz.

Uç noktalar

POST/generations

Üretim başlat

Görsel, video, ses ya da metin üretimini kuyruğa alır. İstek hemen döner; sonucu durum sorgusuyla ya da webhook ile alırsın.

typezorunlu: "image" | "video" | "audio" | "text" — Üretim türü
modelzorunlu: string — Model kimliği, ör. aurora-2 (bkz. /models)
promptzorunlu: string — Ne üretileceğinin tarifi
settings: object — Moda göre ayarlar: aspect_ratio, count, duration, voice…
reference_url: string — Görselden üretim için herkese açık görsel URL'si
webhook_url: string — Üretim bitince POST edilecek adres

curl -X POST https://api.nuvio.app/v1/generations \
  -H "Authorization: Bearer $NUVIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "aurora-2",
    "prompt": "Mountain lake on a misty morning, cinematic light",
    "settings": {
      "aspect_ratio": "16:9",
      "count": 2
    }
  }'

Yanıt · 200

{
  "id": "gen_8fKq2x",
  "status": "queued",
  "type": "image",
  "model": "aurora-2",
  "cost": 8,
  "created_at": "2026-10-14T09:30:00Z"
}

GET/generations/{id}

Üretim durumunu al

Durum queued → running → succeeded | failed şeklinde ilerler. Bitince outputs alanı dolar; çıktı URL'leri 24 saat geçerlidir.

curl https://api.nuvio.app/v1/generations/gen_8fKq2x \
  -H "Authorization: Bearer $NUVIO_API_KEY"

Yanıt · 200

{
  "id": "gen_8fKq2x",
  "status": "succeeded",
  "type": "image",
  "outputs": [
    {
      "url": "https://cdn.nuvio.app/o/gen_8fKq2x/0.webp",
      "width": 1920,
      "height": 1080
    }
  ],
  "cost": 8,
  "finished_at": "2026-10-14T09:30:07Z"
}

GET/generations?limit=20

Üretimleri listele

En yeniden eskiye sıralı; sayfalama için cursor parametresini kullan.

curl https://api.nuvio.app/v1/generations?limit=20 \
  -H "Authorization: Bearer $NUVIO_API_KEY"

Yanıt · 200

{
  "data": [
    {
      "id": "gen_8fKq2x",
      "status": "succeeded",
      "type": "image"
    }
  ],
  "next_cursor": "c_19ab"
}

DELETE/generations/{id}

Üretimi iptal et

Yalnız queued durumundaki işler iptal edilir; kredi iade edilir.

curl -X DELETE https://api.nuvio.app/v1/generations/gen_8fKq2x \
  -H "Authorization: Bearer $NUVIO_API_KEY"

Yanıt · 200

{
  "id": "gen_8fKq2x",
  "status": "cancelled",
  "refunded": 8
}

GET/models

Modelleri listele

Kullanabileceğin modeller, türleri, desteklenen ayarlar ve kredi maliyetleri.

curl https://api.nuvio.app/v1/models \
  -H "Authorization: Bearer $NUVIO_API_KEY"

Yanıt · 200

{
  "data": [
    {
      "id": "aurora-2",
      "type": "image",
      "cost": 4,
      "settings": [
        "aspect_ratio",
        "count",
        "quality"
      ]
    }
  ]
}

GET/account/credits

Kredi bakiyesi

Hesabının kalan kredisi.

curl https://api.nuvio.app/v1/account/credits \
  -H "Authorization: Bearer $NUVIO_API_KEY"

Yanıt · 200

{
  "balance": 224,
  "currency": "credits"
}

Modeller ve ayarlar

Stüdyo'daki modeller ve ayarlar API'de birebir aynıdır. settings alanına aşağıdaki anahtarları gönder.

type	model	Maliyet	settings
`image`	`aurora-2`Fotoğraf gerçekliği, net ışık	4 kredi	aspect_ratio: 1:1 \| 3:4 \| 4:3 \| 16:9 \| 9:16count: 1 \| 2 \| 3 \| 4quality: standard \| hd
`image`	`prisma-xl`İllüstrasyon ve sanat stilleri	5 kredi	aspect_ratio: 1:1 \| 3:4 \| 4:3 \| 16:9 \| 9:16count: 1 \| 2 \| 3 \| 4quality: standard \| hd
`image`	`lumen-fast`Saniyeler içinde taslak	2 kredi	aspect_ratio: 1:1 \| 3:4 \| 4:3 \| 16:9 \| 9:16count: 1 \| 2 \| 3 \| 4quality: standard \| hd
`video`	`kinetik-2`Sinematik kamera hareketleri	18 kredi	aspect_ratio: 16:9 \| 9:16 \| 1:1duration: 5 \| 10motion: auto \| push \| orbit \| pan \| static
`video`	`kinetik-turbo`Kısa, hızlı klipler	10 kredi	aspect_ratio: 16:9 \| 9:16 \| 1:1duration: 5 \| 10motion: auto \| push \| orbit \| pan \| static
`audio`	`echo-voice`Metinden doğal seslendirme	3 kredi	voice: ayla \| deniz \| kerem \| mira
`audio`	`echo-music`Tariften müzik ve jingle	8 kredi	duration: 15 \| 30 \| 60genre: lofi \| cinematic \| pop \| ambient
`text`	`scribe`Başlık, açıklama, senaryo	1 kredi	tone: neutral \| friendly \| formallength: short \| medium \| long
`text`	`scribe-mini`Kısa ve hızlı metinler	1 kredi	tone: neutral \| friendly \| formallength: short \| medium \| long

Webhook'lar

İstekte webhook_url verirsen üretim bittiğinde bu adrese POST atarız. İmzayı X-Nuvio-Signature başlığıyla (HMAC-SHA256) doğrula.

{
  "event": "generation.succeeded",
  "data": {
    "id": "gen_8fKq2x",
    "status": "succeeded",
    "type": "image",
    "outputs": [
      {
        "url": "https://cdn.nuvio.app/o/gen_8fKq2x/0.webp",
        "width": 1920,
        "height": 1080
      }
    ],
    "cost": 8,
    "finished_at": "2026-10-14T09:30:07Z"
  }
}

2xx dönmeyen webhook'lar üstel bekleme ile 24 saat boyunca yeniden denenir.

Hatalar

Hatalar her zaman aynı biçimde döner:

JSON

{
  "error": {
    "code": "insufficient_credits",
    "message": "This generation costs 8 credits; you have 3.",
    "request_id": "req_1Xc9"
  }
}

HTTP	code	Anlamı
400	`invalid_request`	Eksik ya da hatalı alan
401	`unauthorized`	Anahtar yok, hatalı ya da iptal edilmiş
402	`insufficient_credits`	Bakiye bu üretim için yetersiz
403	`forbidden`	Anahtarın bu işlem için izni yok
404	`not_found`	Kaynak bulunamadı
422	`content_rejected`	Prompt içerik politikasına takıldı
429	`rate_limited`	Hız limiti aşıldı; Retry-After başlığına bak
500	`server_error`	Bizim tarafta hata; tekrar dene

Hız limitleri

istek / dakika (anahtar başına)

eşzamanlı üretim

24 sa

çıktı URL'lerinin geçerliliği

Her yanıtta X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 aldığında Retry-After süresi kadar bekle.

Nuvio, Model Context Protocol sunucusu da sunar. Claude, Cursor ya da VS Code gibi bir MCP istemcisini bağladığında asistanın senin adına üretim başlatabilir, durumu sorgulayabilir ve bakiyeni görebilir. Kimlik doğrulama REST API ile aynı anahtarı kullanır.

https://api.nuvio.app/mcp

generate_image
Metinden ya da referans görselden görsel üretir
generate_video
Metinden ya da görselden kısa video üretir
generate_audio
Seslendirme ya da müzik üretir
generate_text
Başlık, açıklama ve senaryo yazar
get_generation
Bir üretimin durumunu ve çıktılarını döner
list_models
Kullanılabilir modelleri ve maliyetleri listeler
get_credits
Kalan kredi bakiyesini döner