Subtitles

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

İstek ve yanıt

POST

https://kolayzeka.com/api/models/subtitles/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/subtitles/generate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "video_url": "Video Url",
    "preset": "glass"
  },
  "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": "subtitles",
    "output_type": "video",
    "source": "api",
    "status": "queued",
    "input_data": {
      "video_url": "Video Url",
      "preset": "glass"
    },
    "output_data": null,
    "thumbnail_url": null,
    "credit_cost": 89622,
    "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": "subtitles",
    "output_type": "video",
    "source": "api",
    "status": "completed",
    "input_data": {
      "video_url": "Video Url",
      "preset": "glass"
    },
    "output_data": {
      "result": "https://<signed-url>/output.mp4"
    },
    "thumbnail_url": "https://<signed-url>/thumb.jpg",
    "credit_cost": 89622,
    "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": "subtitles",
    "output_type": "video",
    "source": "api",
    "status": "failed",
    "input_data": {
      "video_url": "Video Url",
      "preset": "glass"
    },
    "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 ≈ 89622 kredi.

POST

https://kolayzeka.com/api/models/subtitles/quote

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

cURL

curl -X POST https://kolayzeka.com/api/models/subtitles/quote \
  -H "Content-Type: application/json" \
  -d '{"input":{"video_url":"Video Url","preset":"glass"}}'

Yanıt

{
  "success": true,
  "data": {
    "credits": 89622,
    "basis": "per_minute",
    "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/subtitles yanıtında.

video_url

zorunlu

string

Video Url · Upload or paste a URL to the video you want to subtitle.

preset

zorunlu

string

Preset · Each style defines fonts, colors, layout, and animation. Two tiers with different pricing: - Dynamic presets (2x multiplier): glass, whisper, glide2, fusion, glide, terminal, handwritten, backdrop, backdrop2. Richer, context-aware rendering that adapts to the input. - Basic presets (1x multiplier): simple, plain, beans, corpo, boo, shadeplay, casper, capri, lowkey, vinta, diego, ali, slay, kitty, hustle, karl, sprout, flex, mint, rizz, vegas. Fixed, lightweight styling with predictable output.

Kabul edilen değerler:"glass""whisper""glide2""fusion""glide""terminal""handwritten""backdrop""backdrop2""simple""plain""beans""corpo""boo""shadeplay""casper""capri""lowkey""vinta""diego""ali""slay""kitty""hustle""karl""sprout""flex""mint""rizz""vegas"

language

isteğe bağlı

string

Language · Improves transcription accuracy, and should match the source audio (not output subtitles).

Kabul edilen değerler:"af-ZA""am-ET""ar-AE""ar-BH""ar-DZ""ar-EG""ar-IL""ar-IQ""ar-JO""ar-KW""ar-LB""ar-MA""ar-OM""ar-PS""ar-QA""ar-SA""ar-TN""ast-ES""az-AZ""ba""bas""be-BY""bg-BG""br""bs-BA""ca-ES""ceb-PH""ckb-IQ""cs-CZ""cy-GB""da-DK""de-DE""dyu""el-GR""en-AU""en-GB""en-IN""en-NZ""en-US""eo""es-AR""es-BO""es-CL""es-CO""es-CR""es-DO""es-EC""es-ES""es-GT""es-HN""es-MX""es-NI""es-PA""es-PE""es-PR""es-PY""es-SV""es-US""es-UY""es-VE""et-EE""eu-ES""fa-IR""ff""fi-FI""fil-PH""fo""fr-CA""fr-FR""fy""ga""gd""gl-ES""ha-NG""haw""he-IL""hr-HR""hsb""ht""hu-HU""hy-AM""id-ID""ig""is-IS""it-IT""ja-JP""ja-Latn-JP""jv-ID""ka-GE""kab""kam-KE""kea-CV""kk-KZ""ko-KR""ku""ky-KG""la""lb-LU""lg""lij""ln-CD""lo-LA""lt-LT""luo-KE""lv-LV""mg""mi-NZ""mk-MK""mn-MN""ms-MY""mt-MT""nb-NO""nl-NL""nso-ZA""ny-MW""oc-FR""pl-PL""ps-AF""pt-BR""pt-PT""ro-RO""roh""ru-RU""rw-RW""sah""sk-SK""sl-SI""sm""sn-ZW""so-SO""sq-AL""sr-Latn-RS""sr-RS""srd""ss""su-ID""sv-SE""sw-KE""sw-TZ""tg-TJ""th-TH""tk""tn""tok""ton""tr-TR""ts-ZA""tt""uk-UA""umb-AO""ur-IN""ur-PK""uz-UZ""vi-VN""vro""wo-SN""xh-ZA""yi""yo-NG""yue-Hant-HK""zh""zh-HK""zh-TW""zu-ZA"

translation_language

isteğe bağlı

string

Translation Language · Translate the subtitles into this language. Omit to keep the original spoken language. If you also pass srt_content or srt_file_url, set `language` to its source language for the most reliable translation.

Kabul edilen değerler:"ab""ace""ach""af-ZA""ak""alz""am-ET""ar-AE""ar-BH""ar-DZ""ar-EG""ar-IL""ar-IQ""ar-JO""ar-KW""ar-LB""ar-MA""ar-OM""ar-PS""ar-QA""ar-SA""ar-TN""awa""ay""az-AZ""ban""bbc""be-BY""bem""bew""bg-BG""bho""bik""bm""bs-BA""bts""btx""bua""ca-ES""ceb-PH""cgg""chm""ckb-IQ""cnh""co""crh""crs""cs-CZ""cv""cy-GB""da-DK""de-DE""din""doi""dov""dv""dz""ee""el-GR""en-AU""en-GB""en-IN""en-NZ""en-US""eo""es-AR""es-BO""es-CL""es-CO""es-CR""es-DO""es-EC""es-ES""es-GT""es-HN""es-MX""es-NI""es-PA""es-PE""es-PR""es-PY""es-SV""es-US""es-UY""es-VE""et-EE""eu-ES""fa-IR""ff""fi-FI""fil-PH""fj""fr-CA""fr-FR""fy""ga""gaa""gd""gl-ES""gn""gom""ha-NG""haw""he-IL""hil""hmn""hr-HR""hrx""ht""hu-HU""hy-AM""id-ID""ig""ilo""is-IS""it-IT""ja-JP""ja-Latn-JP""jv-ID""ka-GE""kk-KZ""ko-KR""kri""ktu""ku""ky-KG""la""lb-LU""lg""li""lij""lmo""ln-CD""lo-LA""lt-LT""ltg""luo-KE""lus""lv-LV""mai""mak""mg""mi-NZ""min""mk-MK""mn-MN""mni-Mtei""ms-Arab""ms-MY""mt-MT""nb-NO""new""nl-NL""nr""nso-ZA""nus""ny-MW""oc-FR""om""pag""pam""pap""pl-PL""ps-AF""pt-BR""pt-PT""qu""rn""ro-RO""rom""ru-RU""rw-RW""scn""sg""shn""sk-SK""sl-SI""sm""sn-ZW""so-SO""sq-AL""sr-Latn-RS""sr-RS""ss""st""su-ID""sv-SE""sw-KE""sw-TZ""szl""tet""tg-TJ""th-TH""ti""tk""tn""tr-TR""ts-ZA""tt""ug""uk-UA""ur-IN""ur-PK""uz-UZ""vi-VN""xh-ZA""yi""yo-NG""yua""yue-Hant-HK""zh""zh-HK""zh-TW""zu-ZA"

srt_file_url

isteğe bağlı

string

SRT File Url · Upload or paste a URL to your .srt subtitles file. When provided, transcription is skipped.

srt_content

isteğe bağlı

string

SRT Content · Paste raw SRT subtitle text. Alternative to srt_file_url. When provided, transcription is skipped.

vocabulary

isteğe bağlı

string

Vocabulary · Optional list of terms to help auto-transcription correctly recognise brand names and domain jargon that providers commonly mis-spell (e.g. "VEED" → "vid"). Ignored when srt_content / srt_file_url is set.

customization

isteğe bağlı

string

Customization · Optional preset overrides: vertical position, shadow intensity, and per-tier text styling (font, weight, hex colour) for each word-importance tier. Any omitted field keeps the preset's default.

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."
    ]
  }
}

Subtitles modeline geri dön