Live Portrait Image

API kılavuzu ve entegrasyon referansı: uç nokta, girdi alanları, fiyatlar, webhook ve hatalar.

İstek ve yanıt

POST

https://kolayzeka.com/api/models/live-portrait-image/generate

Gövde: { "input": {…alanlar}, "category_id"?: sayı, "webhook_url"?: "https://…" }. Alanlar aşağıda; tanımlı olmayan bir alan 422 döner.

cURL · JSON

curl -X POST https://kolayzeka.com/api/models/live-portrait-image/generate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "image_url": "https://cdn.example.com/input.jpg",
    "blink": 0,
    "eyebrow": 0,
    "wink": 0,
    "pupil_x": 0,
    "pupil_y": 0,
    "aaa": 0,
    "eee": 0,
    "woo": 0,
    "smile": 0,
    "rotate_pitch": 0,
    "rotate_yaw": 0,
    "rotate_roll": 0,
    "flag_pasteback": true,
    "flag_do_crop": true,
    "flag_do_rot": true,
    "flag_lip_zero": true,
    "dsize": 512,
    "scale": 2.3,
    "vx_ratio": 0,
    "vy_ratio": -0.125,
    "enable_safety_checker": false,
    "output_format": "jpeg"
  },
  "webhook_url": "https://your-server.com/hooks/kolayzeka"
}'

cURL · multipart (dosya yükleyerek)

curl -X POST https://kolayzeka.com/api/models/live-portrait-image/generate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F 'input[blink]=0' \
  -F 'input[eyebrow]=0' \
  -F 'input[wink]=0' \
  -F 'input[pupil_x]=0' \
  -F 'input[pupil_y]=0' \
  -F 'input[aaa]=0' \
  -F 'input[eee]=0' \
  -F 'input[woo]=0' \
  -F 'input[smile]=0' \
  -F 'input[rotate_pitch]=0' \
  -F 'input[rotate_yaw]=0' \
  -F 'input[rotate_roll]=0' \
  -F 'input[flag_pasteback]=true' \
  -F 'input[flag_do_crop]=true' \
  -F 'input[flag_do_rot]=true' \
  -F 'input[flag_lip_zero]=true' \
  -F 'input[dsize]=512' \
  -F 'input[scale]=2.3' \
  -F 'input[vx_ratio]=0' \
  -F 'input[vy_ratio]=-0.125' \
  -F 'input[enable_safety_checker]=false' \
  -F 'input[output_format]=jpeg' \
  -F 'input[image_url]=@./image_url.jpg' \
  -F 'webhook_url=https://your-server.com/hooks/kolayzeka'

Üretim asenkrondur. POST, 202 ve status: "queued" döner; sonuç henüz yoktur. Sonucu GET https://kolayzeka.com/api/generations/{id} ile sorgulayın ya da webhook_url verin (aynı nesne gelir). Durumlar: queued → processing → completed | failed. estimated_seconds bu modun geçmiş ortalama süresidir (null olabilir).

1 · POST yanıtı (202)

{
  "data": {
    "id": "9d1c…-uuid",
    "model": "live-portrait-image",
    "output_type": "image",
    "source": "api",
    "status": "queued",
    "input_data": {
      "image_url": "https://cdn.example.com/input.jpg",
      "blink": 0,
      "eyebrow": 0,
      "wink": 0,
      "pupil_x": 0,
      "pupil_y": 0,
      "aaa": 0,
      "eee": 0,
      "woo": 0,
      "smile": 0,
      "rotate_pitch": 0,
      "rotate_yaw": 0,
      "rotate_roll": 0,
      "flag_pasteback": true,
      "flag_do_crop": true,
      "flag_do_rot": true,
      "flag_lip_zero": true,
      "dsize": 512,
      "scale": 2.3,
      "vx_ratio": 0,
      "vy_ratio": -0.125,
      "enable_safety_checker": false,
      "output_format": "jpeg"
    },
    "output_data": null,
    "thumbnail_url": null,
    "credit_cost": 11203,
    "duration": null,
    "estimated_seconds": 12,
    "error_message": null,
    "webhook_url": "https://your-server.com/hooks/kolayzeka",
    "created_at": "2026-06-29T12:00:00.000000Z",
    "updated_at": "2026-06-29T12:00:00.000000Z"
  },
  "success": true
}

2 · Tamamlandı (GET /generations/{id} veya webhook)

{
  "data": {
    "id": "9d1c…-uuid",
    "model": "live-portrait-image",
    "output_type": "image",
    "source": "api",
    "status": "completed",
    "input_data": {
      "image_url": "https://cdn.example.com/input.jpg",
      "blink": 0,
      "eyebrow": 0,
      "wink": 0,
      "pupil_x": 0,
      "pupil_y": 0,
      "aaa": 0,
      "eee": 0,
      "woo": 0,
      "smile": 0,
      "rotate_pitch": 0,
      "rotate_yaw": 0,
      "rotate_roll": 0,
      "flag_pasteback": true,
      "flag_do_crop": true,
      "flag_do_rot": true,
      "flag_lip_zero": true,
      "dsize": 512,
      "scale": 2.3,
      "vx_ratio": 0,
      "vy_ratio": -0.125,
      "enable_safety_checker": false,
      "output_format": "jpeg"
    },
    "output_data": {
      "result": "https://<signed-url>/output.jpg"
    },
    "thumbnail_url": "https://<signed-url>/thumb.jpg",
    "credit_cost": 11203,
    "duration": 4.52,
    "estimated_seconds": 12,
    "error_message": null,
    "webhook_url": "https://your-server.com/hooks/kolayzeka",
    "created_at": "2026-06-29T12:00:00.000000Z",
    "updated_at": "2026-06-29T12:00:05.000000Z"
  },
  "success": true
}

3 · Başarısız

{
  "data": {
    "id": "9d1c…-uuid",
    "model": "live-portrait-image",
    "output_type": "image",
    "source": "api",
    "status": "failed",
    "input_data": {
      "image_url": "https://cdn.example.com/input.jpg",
      "blink": 0,
      "eyebrow": 0,
      "wink": 0,
      "pupil_x": 0,
      "pupil_y": 0,
      "aaa": 0,
      "eee": 0,
      "woo": 0,
      "smile": 0,
      "rotate_pitch": 0,
      "rotate_yaw": 0,
      "rotate_roll": 0,
      "flag_pasteback": true,
      "flag_do_crop": true,
      "flag_do_rot": true,
      "flag_lip_zero": true,
      "dsize": 512,
      "scale": 2.3,
      "vx_ratio": 0,
      "vy_ratio": -0.125,
      "enable_safety_checker": false,
      "output_format": "jpeg"
    },
    "output_data": null,
    "thumbnail_url": null,
    "credit_cost": 0,
    "duration": null,
    "estimated_seconds": 12,
    "error_message": "Sağlayıcı yoğun, lütfen tekrar deneyin.",
    "webhook_url": "https://your-server.com/hooks/kolayzeka",
    "created_at": "2026-06-29T12:00:00.000000Z",
    "updated_at": "2026-06-29T12:00:00.000000Z"
  },
  "success": true
}

Sonuç output_data.result alanındadır (imzalı URL, süreli: kalıcı tutmak için kendi depolamanıza indirin).
Medya URL'leri imzalıdır ve süresi dolar; eski bir URL için işi tekrar GET edin, taze URL gelir.
Geçmiş: GET https://kolayzeka.com/api/generations (en yeni önce, sayfa başına 20, ?page=).

Fiyat ve teklif

Fiyat kredi cinsindendir ve seçtiğiniz seçeneklere (kalite, boyut, süre, adet…) göre değişir. Varsayılan ayarlarla bu mod ≈ 11203 kredi.

POST

https://kolayzeka.com/api/models/live-portrait-image/quote

Çalıştırmadan, tam bu girdinin fiyatı. Token gerekmez; girdiyi üretimdeki gibi doğrular.

cURL

curl -X POST https://kolayzeka.com/api/models/live-portrait-image/quote \
  -H "Content-Type: application/json" \
  -d '{"input":{"image_url":"https://cdn.example.com/input.jpg","blink":0,"eyebrow":0,"wink":0,"pupil_x":0,"pupil_y":0,"aaa":0,"eee":0,"woo":0,"smile":0,"rotate_pitch":0,"rotate_yaw":0,"rotate_roll":0,"flag_pasteback":true,"flag_do_crop":true,"flag_do_rot":true,"flag_lip_zero":true,"dsize":512,"scale":2.3,"vx_ratio":0,"vy_ratio":-0.125,"enable_safety_checker":false,"output_format":"jpeg"}}'

Yanıt

{
  "success": true,
  "data": {
    "credits": 11203,
    "basis": "per_generation",
    "exact": true,
    "mode": {
      "category_id": null,
      "label": "Mod"
    }
  }
}

exact: false: fiyat çıktıya bağlı (ör. token, gerçek süre); teklif tipik değerle hesaplanır.
Kredi, istek kabul edilince teklif tutarı kadar ayrılır. İş bitince gerçek tutara göre fark düşülür ya da iade edilir; iş başarısız olursa tamamı iade edilir. Kesin tutar: sonuçtaki credit_cost.
Bakiye: GET https://kolayzeka.com/api/me → credit_balance. Yetmezse 402 insufficient_credits.

Girdi alanları

input içine gönderilir. Tip etiketi gönderilecek JSON değeridir (string, integer, number, boolean, url, array<url>). Aynı liste makine-okunur olarak GET https://kolayzeka.com/api/ai-models/live-portrait-image yanıtında.

image_url

zorunlu

url

dosya

Image Url · URL of the image to be animated

JSON'da herkese açık bir https URL gönderin, ya da dosyayı multipart ile yükleyin: -F 'input[image_url]=@./dosya.jpg'

blink

isteğe bağlı

number

Blink · Amount to blink the eyes

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -30 · en çok 30

eyebrow

isteğe bağlı

number

Eyebrow · Amount to raise or lower eyebrows

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -30 · en çok 30

wink

isteğe bağlı

number

Wink · Amount to wink

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az 0 · en çok 25

pupil_x

isteğe bağlı

number

Pupil X · Amount to move pupils horizontally

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -45 · en çok 45

pupil_y

isteğe bağlı

number

Pupil Y · Amount to move pupils vertically

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -45 · en çok 45

aaa

isteğe bağlı

number

Aaa · Amount to open mouth in 'aaa' shape

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -200 · en çok 200

eee

isteğe bağlı

number

Eee · Amount to shape mouth in 'eee' position

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -40 · en çok 40

woo

isteğe bağlı

number

Woo · Amount to shape mouth in 'woo' position

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -100 · en çok 100

smile

isteğe bağlı

number

Smile · Amount to smile

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -2 · en çok 2

rotate_pitch

isteğe bağlı

number

Rotate Pitch · Amount to rotate the face in pitch

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -45 · en çok 45

rotate_yaw

isteğe bağlı

number

Rotate Yaw · Amount to rotate the face in yaw

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -45 · en çok 45

rotate_roll

isteğe bağlı

number

Rotate Roll · Amount to rotate the face in roll

Varsayılan: 0 (gönderilmezse bu kullanılır)

Sınırlar: en az -45 · en çok 45

flag_pasteback

isteğe bağlı

boolean

Flag Pasteback · Whether to paste-back/stitch the animated face cropping from the face-cropping space to the original image space.

Varsayılan: true (gönderilmezse bu kullanılır)

flag_do_crop

isteğe bağlı

boolean

Flag Do Crop · Whether to crop the source portrait to the face-cropping space.

Varsayılan: true (gönderilmezse bu kullanılır)

flag_do_rot

isteğe bağlı

boolean

Flag Do Rot · Whether to conduct the rotation when flag_do_crop is True.

Varsayılan: true (gönderilmezse bu kullanılır)

flag_lip_zero

isteğe bağlı

boolean

Flag Lip Zero · Whether to set the lip to closed state before animation. Only takes effect when flag_eye_retargeting and flag_lip_retargeting are False.

Varsayılan: true (gönderilmezse bu kullanılır)

dsize

isteğe bağlı

number

Dsize · Size of the output image.

Varsayılan: 512 (gönderilmezse bu kullanılır)

scale

isteğe bağlı

number

Scale · Scaling factor for the face crop.

Varsayılan: 2.3 (gönderilmezse bu kullanılır)

vx_ratio

isteğe bağlı

number

Vx Ratio · Horizontal offset ratio for face crop.

Varsayılan: 0 (gönderilmezse bu kullanılır)

vy_ratio

isteğe bağlı

number

Vy Ratio · Vertical offset ratio for face crop. Positive values move up, negative values move down.

Varsayılan: -0.125 (gönderilmezse bu kullanılır)

enable_safety_checker

isteğe bağlı

boolean

Enable Safety Checker · Whether to enable the safety checker. If enabled, the model will check if the input image contains a face before processing it. The safety checker will process the input image

Varsayılan: false (gönderilmezse bu kullanılır)

output_format

isteğe bağlı

string

Output Format · Output format

Kabul edilen değerler:"jpeg""png"

Varsayılan: "jpeg" (gönderilmezse bu kullanılır)

Kimlik doğrulama

Her istekte Authorization: Bearer YOUR_API_TOKEN. Token'ı Profil sayfasında oluşturun. Katalog ve teklif (/ai-models, /quote) token istemez. Ayrıntılar: geliştirici rehberi.

Webhook

İsteğe bir webhook_url (https) ekleyin; iş bitince oraya imzalı bir POST gelir. Gövde { event, success, data }: data, durum endpoint'inin döndüğü nesnenin aynısıdır. Sorgulamaya gerek kalmaz; uzun işler (video, çok adımlı uygulamalar) için önerilir.

Gelen başlıklar

X-KolayZeka-Event: generation.completed // veya generation.failed

X-KolayZeka-Signature: sha256=<hex>

User-Agent: KolayZeka-Webhook/1.0

İmza = ham gövdenin, hesabınızın webhook imzalama anahtarı ile HMAC-SHA256'sı. Anahtarı Profil sayfasında oluşturun (bir kez gösterilir). Anahtar yoksa webhook gönderilmez.

Doğrulama · Node.js

import crypto from 'node:crypto';

// rawBody: the request body exactly as received (before JSON.parse).
const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.KOLAYZEKA_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
const given = req.headers['x-kolayzeka-signature'] ?? '';

if (given.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given))) {
  return res.status(401).end();
}

Doğrulama · PHP / Laravel

$expected = 'sha256='.hash_hmac('sha256', $request->getContent(), config('services.kolayzeka.webhook_secret'));

abort_unless(hash_equals($expected, (string) $request->header('X-KolayZeka-Signature')), 401);

2xx dönün. Diğer yanıtlar ve ağ hataları 30 sn arayla en çok 5 kez yeniden denenir.
Aynı iş için birden fazla gelebilir: data.id ile tekilleştirin.
Özel / iç ağ / bulut-metadata adresleri reddedilir (422 invalid_webhook_url).

Hatalar

Her hata aynı şekildedir: { success: false, code, error, … }. Kodunuzu code'a göre yazın; error insan için mesajdır.

HTTP	code	Ne zaman
400	invalid_mode	Modelin şu an çalıştırılabilir bir modu yok (geçici; başka model deneyin).
401	unauthenticated	Bearer token yok, geçersiz ya da iptal edilmiş.
402	insufficient_credits	Bakiye yetmiyor. Yanıtta balance (bakiye) ve required (gereken) var.
403	forbidden	Bu kaynağa erişim yetkiniz yok.
404	not_found	Model / uygulama / iş yok, aktif değil ya da size ait değil.
405	method_not_allowed	Endpoint bu HTTP metodunu kabul etmiyor.
422	validation_failed	Girdi şemaya uymuyor. errors alanı: alan → mesajlar.
422	invalid_webhook_url	webhook_url https değil, çözümlenmiyor ya da özel / iç ağ adresi.
429	rate_limited	Hız sınırı aşıldı. retry_after saniye sonra tekrar deneyin.
500	server_error	Beklenmeyen hata. Tekrar denemeden önce listeden (GET /api/generations) işin oluşup oluşmadığına bakın.

402 örneği

{
  "success": false,
  "code": "insufficient_credits",
  "error": "Yetersiz kredi. Bakiye: 40, Gerekli: 55",
  "balance": 40,
  "required": 55
}

422 örneği

{
  "success": false,
  "code": "validation_failed",
  "error": "Doğrulama başarısız oldu.",
  "errors": {
    "quality": [
      "`quality` alanı şunlardan biri olmalıdır: low, medium, high."
    ]
  }
}

Live Portrait Image modeline geri dön