Dosya yükleme

Kendi ses veya video dosyanızı yüklediğinizde kaydı yapay zeka ile yazıya çeviririz. source için yalnızca auto ve stt kabul edilir. Dil ve konuşmacı ayırma ayarları için Kaynaklar ve seçenekler sayfasındaki language ve diarize açıklamalarını okuyun.

Hangi dosyaları yükleyebilirsiniz?

Dosya uzantısı mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm veya mkv olmalıdır. Farklı bir uzantı gönderirseniz 422 unsupported_media alırsınız. Dosyanın ses kanalı da bulunmalıdır; yoksa transkripsiyon unsupported_media hatasıyla sona erer.

Dosya limitinizi aşarsanız 413 media_too_large alırsınız. Hata yanıtındaki max_bytes alanı izin verilen boyutu gösterir.

Dosyayı tek istekte gönderin

95 MB'a kadar dosyalar için POST /v1/transcriptions ile bir multipart/form-data isteği gönderin. Dosyayı file alanına ekleyin. İsterseniz forma language, diarize (true veya false), source (auto veya stt) ve webhook_url alanlarını da ekleyebilirsiniz.

curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F [email protected] \
  -F language=en \
  -F diarize=true

API, source.platform alanı upload olan bir transkripsiyon nesnesi döndürür. Video bağlantılarında olduğu gibi işlem sürüyorsa HTTP kodu 202, sona erdiyse 200 olur. Boş dosya gönderirseniz 422 invalid_request alırsınız.

Büyük dosyaları parçalar halinde gönderin

Büyük dosyalarda yüklemeyi parçalara bölün. Böylece bağlantı kesildiğinde dosyanın tamamını baştan göndermeniz gerekmez. Yükleme dört adımda tamamlanır.

1. Yüklemeyi başlatın

Önce dosya adını ve boyutunu JSON olarak gönderin. mime_type zorunlu değildir. Aynı isteği güvenle tekrar gönderebilmek için Idempotency-Key başlığı ekleyin:

curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Idempotency-Key: interview-2026-10-13" \
  -H "Content-Type: application/json" \
  -d '{"upload":{"filename":"interview.m4a","size":48210334,"mime_type":"audio/mp4"},"language":"auto","diarize":true}'

API, HTTP 201 döndürür. Transkripsiyon awaiting_upload durumundadır; parçaları nasıl göndereceğiniz upload bloğunda bulunur:

{
  "id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
  "object": "transcription",
  "status": "awaiting_upload",
  "upload": {
    "chunk_url_template": "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/chunks/{index}",
    "headers": { "X-Upload-Token": "t1u_..." },
    "expires_at": "2026-10-13T10:30:00.000Z",
    "chunks": [
      { "index": 0, "offset": 0, "size": 8388608 },
      { "index": 1, "offset": 8388608, "size": 8388608 }
    ]
  }
}

Parça boyutlarını sunucu belirler. Parçalar yaklaşık 8 MiB (8.388.608 bayt) büyüklüğündedir; listeyi chunks alanında alırsınız. Yukarıdaki liste kısaltılmıştır. X-Upload-Token yalnızca bu yükleme için geçerli gizli bir token'dır. Geçerlilik süresi 1 saattir; bitiş zamanını expires_at gösterir.

2. Parçaları yükleyin

Her parça için chunk_url_template içindeki {index} yerine o parçanın index değerini koyun ve bu adrese PUT gönderin. Dosyayı offset konumundan okuyup tam size bayt gönderin. İçerik türü application/octet-stream olmalıdır. Eksik veya fazla bayt göndermeyin. Kimlik doğrulama için X-Upload-Token başlığı yeterlidir; bu çağrıda Authorization gerekmez.

curl -X PUT "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/chunks/0" \
  -H "X-Upload-Token: t1u_..." \
  -H "Content-Type: application/octet-stream" \
  --data-binary @chunk-0.bin

Parça yüklendiğinde { "object": "upload_chunk", "index": 0, "size": 8388608 } benzeri bir yanıt alırsınız. Aynı parçayı tekrar gönderirseniz eskisinin üzerine yazılır. Boyut yanlışsa veya index parça listesinde yoksa 422 invalid_request döner. Token eksikse ya da süresi dolmuşsa 401 unauthorized alırsınız.

3. Bağlantı kesilirse eksik parçalardan devam edin

Hangi parçaların yüklendiğini GET /v1/transcriptions/:id/upload ile kontrol edin:

{
  "object": "upload",
  "status": "awaiting_upload",
  "total_bytes": 48210334,
  "uploaded_bytes": 16777216,
  "received_chunks": [0, 1],
  "chunks": [ { "index": 0, "offset": 0, "size": 8388608 } ],
  "expires_at": "2026-10-13T10:30:00.000Z"
}

received_chunks listesinde bulunmayan parçaları gönderin; diğerlerini tekrar yüklemeniz gerekmez. Token'ın süresi dolmuşsa 1. adımdaki isteği aynı parametreler ve aynı Idempotency-Key ile yeniden gönderin. Yeni bir transkripsiyon oluşmaz; aynı transkripsiyon için yeni bir yükleme token'ı alırsınız.

4. Yüklemeyi tamamlayın

curl -X POST "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/complete" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY"

POST /v1/transcriptions/:id/upload/complete çağrısı, tüm parçaların doğru boyutta ulaştığını kontrol eder. Ardından dosyayı birleştirir ve transkripsiyonu kuyruğa ekler. Yanıtta HTTP 202 ve transkripsiyon nesnesi bulunur.

Eksik parça varsa 409 upload_incomplete alırsınız. missing_chunks listesinde belirtilen parça numaralarını yeniden gönderin. Yüklemeyi daha önce tamamladıysanız veya iptal ettiyseniz 409 invalid_state döner. Tamamladıktan sonra GET /v1/transcriptions/:id?wait=60 ile durumu takip edin ya da webhook kullanın.

Tüm yükleme adımları Python ile

import os
import requests
 
API = "https://api.transcript1.com"
auth = {"Authorization": f"Bearer {os.environ['TRANSCRIPT1_API_KEY']}"}
path = "interview.m4a"
 
created = requests.post(
    f"{API}/v1/transcriptions",
    headers={**auth, "Idempotency-Key": "interview-2026-10-13"},
    json={"upload": {"filename": os.path.basename(path), "size": os.path.getsize(path)}},
)
created.raise_for_status()
transcription = created.json()
upload = transcription["upload"]
 
with open(path, "rb") as file:
    for chunk in upload["chunks"]:
        file.seek(chunk["offset"])
        url = upload["chunk_url_template"].replace("{index}", str(chunk["index"]))
        response = requests.put(
            url,
            data=file.read(chunk["size"]),
            headers={**upload["headers"], "Content-Type": "application/octet-stream"},
        )
        response.raise_for_status()
 
done = requests.post(f"{API}/v1/transcriptions/{transcription['id']}/upload/complete", headers=auth)
done.raise_for_status()
print(done.json()["status"])

Limitler ve dosyaların silinme süresi

• Bir ekip aynı anda en fazla 20 yüklemeyi açık tutabilir (awaiting_upload). Daha fazlasını başlatırsanız Retry-After başlığıyla birlikte 429 too_many_active_jobs alırsınız.
• Başlattığınız yüklemeyi 24 saat içinde tamamlamazsanız iptal eder, yüklenen parçaları sileriz.
• Transkripsiyon completed, failed veya canceled durumuna geldikten 24 saat sonra ses veya video dosyanızı sileriz. Transkript, siz DELETE /v1/transcriptions/:id ile silene kadar hesabınızda kalır.
• Transkripsiyon başarısız olursa veya iptal edilirse dakika harcamazsınız. Dosyanın süresini belirlediğimizde her başlayan dakika için ücret hesaplarız. Ayrıntılar Ücretlendirme ve limitler sayfasında.