REST API kullanımı

İlk isteği doğrulayın

Planlanan adres https://api.captionbolt.com. Erişim açıldığında anahtarı yalnızca Authorization Bearer başlığında gönderin. Çerezler ve URL parametrelerindeki anahtarlar kabul edilmez. İstekleri sunucunuzdan yapın; anahtarı tarayıcıda açığa çıkarmayın veya yönlendirmelerde iletmeyin.

# CAPTIONBOLT_API_KEY: injected by your secret manager
curl --fail-with-body https://api.captionbolt.com/v1/account \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY"

Güncel sınırları /v1/account, stilleri GET /v1/styles, kendi ön ayarlarınızı GET /v1/presets ile okuyun. Listeler search, limit (1–100, varsayılan 50) ve offset kabul eder.

Hizmet durumunu kontrol edin

GET /health/integrations herkese açıktır ve API anahtarı gerektirmez. REST API, MCP ve Webhook teslimatı çalışır durumdaysa HTTP 200, kullanılamıyorsa HTTP 503 döndürür. Bu, kimlik doğrulamalı uçtan uca istek değil, pasif bir hazırlık kontrolüdür.

Videoyu yükleyin

Yerel MCP bilgisayardaki yüklemeyi yönetir. Kendi entegrasyonunuz için:

Idempotency-Key başlığı ve gerçek dosya bilgileriyle POST /v1/uploads gönderin. Aşağıdaki değerler örnektir, tekrar kullanılabilir dosya kimliği değildir.
İşlemi completed olana kadar sorgulayın; son resourceId yükleme kimliğidir.
partSize, partCount ve completedPartNumbers için GET /v1/uploads/{uploadId} okuyun.
Eksik parçaları POST /v1/uploads/{uploadId}/parts ve {"partNumbers":[1]} ile imzalayın; istek başına en fazla 32 parça. Her parçayı tam bayt uzunluğuyla kendi URL’sine PUT edin. API Key’i depolama adresine göndermeyin.
Tüm parçalardan sonra POST /v1/uploads/{uploadId}/complete adresine boş JSON nesnesi gönderin, ardından projeyi oluşturun.

{
  "fileName": "lesson.mp4",
  "fileSize": 10485760,
  "durationSec": 60,
  "lastModifiedMs": 1789000000000,
  "contentType": "video/mp4",
  "fingerprint": "<64-character-lowercase-sha256>"
}

Ölçülen süreyi saniye cinsinden durationSec alanında gönderin. Bu alanı atlarsanız sunucu, planınızın izin verdiği en uzun video süresi kadar dakika ayırır. Kalan dakika daha azsa kısa bir video da reddedilebilir. Sunucu, işlemeden önce gerçek süreyi doğrular.

Parmak izini orijinal ad, boyut, değişiklik zamanı, MIME ve çakışmayan ilk/son 64 KiB üzerinden hesaplayın. Node.js örneği, seçilen File nesnesinin orijinal bilgilerini kullanır:

import { createHash } from "node:crypto";

// file: the exact selected File, with its original name and lastModified
const prefix = `captionbolt-upload-v1\0${file.name}\0${file.size}\0${file.lastModified}\0${file.type}`;
const first = await file.slice(0, 65536).arrayBuffer();
const last = await file.slice(Math.max(65536, file.size - 65536)).arrayBuffer();
const fingerprint = createHash("sha256")
  .update(prefix, "utf8")
  .update(Buffer.from(first))
  .update(Buffer.from(last))
  .digest("hex");

Devam etmek için aynı dosyayı seçin, bilgileri ve parmak izini GET /v1/uploads/{uploadId} ile karşılaştırın, sonra açıkça POST /v1/uploads/{uploadId}/resume çağırın. DELETE /v1/uploads/{uploadId} kullanılmamış yüklemeyi durdurur; oluşturulmuş projeyi iptal etmez.

Projeyi oluşturup izleyin

curl --fail-with-body https://api.captionbolt.com/v1/projects \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: video-001-create' \
  --data '{"uploadSessionId":"<uploaded-session-uuid>","mode":"review"}'

Yükleme UUID’sini değiştirin. language ve styleId ya da presetId eklenebilir; son ikisi birlikte gönderilemez. İkisi de yoksa varsayılan stil kullanılır. Varsayılan mod review; auto-export ayrıca exports:write ister.

Oluşturma, dışa aktarma, yeniden deneme ve iptal HTTP 202 ile işlem döndürür:

{
  "id": "operation-uuid",
  "resourceId": "resource-uuid",
  "state": "pending",
  "error": null,
  "pollAfterSeconds": 2
}

pollAfterSeconds aralığıyla GET /v1/operations/{id} sorgulayın. İşlemin completed olması videonun bittiği anlamına gelmez. Sonra GET /v1/projects/{projectId} veya /status okuyun: processing, ready, exporting, completed, failed veya cancelled.

Zaman aşımından sonra aynı komutu ilk Idempotency-Key ile tekrarlayın; yeni amaç için yeni anahtar kullanın. Anahtar boşluksuz, yazdırılabilir 1–128 ASCII karakteridir. Aynı anahtarla farklı veri 409 döndürür.

Kaydedilmiş sonucu dışa aktarın

review modunda düzenleyicide inceleyip kaydedin. PROJECT_ID değerini proje kimliği olarak ayarlayın:

curl --fail-with-body "https://api.captionbolt.com/v1/projects/$PROJECT_ID/export" \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: video-001-export' \
  --data '{"outputFormats":["mp4"]}'

Dışa aktarma en son kaydedilen belgeyi kullanır; kaydedilmemiş değişiklikleri içermez. outputFormats plana bağlı olarak mp4, srt, vtt, ass, txt kabul eder; varsayılan MP4’tür. Auto-export ready durumunda kalırsa projenin autoExport işlemindeki hatayı inceleyin.

Proje completed olduğunda GET /v1/projects/{projectId}/result çağırın. Bağlantılar en fazla on dakika geçerlidir ve proje erişimini uzatmaz. expiresAt değerini kontrol edip zamanında kaydedin. Bitmiş dışa aktarımları değiştirmek için CaptionBolt’ta düzenlenebilir kopya oluşturun.

Hataları çözün

400: girdileri ve idempotency başlığını kontrol edin.
401 / 403: süreyi, iptali ve izinleri kontrol edin; yalnız yazma izni ilerlemeyi okuyamaz.
404: kimliği, hesabı ve erişim süresini doğrulayın. Silinen veya süresi dolan kaynaklara erişilemez.
409: durumu ve anahtarla ilişkilendirilmiş veriyi kontrol edin.
429: Retry-After kadar bekleyin; tüm hesap anahtarları dakikada 120 isteği paylaşır.
503 veya zaman aşımı: bekleyin, işlemi sorgulayın veya ilk anahtarla tekrarlayın. Yanıtın kaybolması başarısızlık kanıtı değildir.

Açık eylemler için ayrı anahtarlarla POST /v1/projects/{projectId}/retry veya /cancel kullanın. Tam şemalar erişim açıldığında API alanındaki /openapi.json ve /docs üzerinden sunulacaktır.