Mengunggah file

File audio dan video yang Anda unggah diproses dengan transkripsi AI. Gunakan source bernilai auto atau stt. Jika ingin menentukan language atau mengaktifkan diarize, baca sumber dan pengaturan transkripsi.

Format file dan ukurannya

Pastikan nama file memakai ekstensi mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm, atau mkv. API menolak ekstensi lain dengan 422 unsupported_media. Rekaman juga harus memiliki track audio. Jika tidak ada, transkripsi gagal dengan unsupported_media.

Jika ukuran file melewati batas, API mengirim 413 media_too_large. Field max_bytes pada error menunjukkan batas ukuran yang berlaku.

Kirim file dalam satu request

Kirim file hingga 95 MB ke POST /v1/transcriptions sebagai multipart/form-data. Gunakan nama part file. Anda juga boleh menambahkan field form language, diarize (true atau false), source (auto atau stt), dan webhook_url.

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 mengirim objek transkripsi dengan source.platform bernilai upload. Seperti saat mengirim link video, kode HTTP-nya 202 selama proses berjalan dan 200 setelah proses berakhir. Jangan kirim file kosong; API akan menolaknya dengan 422 invalid_request.

Unggah file besar per chunk

Untuk file besar, kirim data secara bertahap dalam beberapa chunk. Anda bisa melanjutkan dari bagian yang belum terkirim jika koneksi terputus. Prosesnya terdiri dari empat langkah berikut.

1. Siapkan sesi unggahan

Mulai dengan mengirim nama dan ukuran file dalam JSON. Isi mime_type jika perlu. Sertakan header Idempotency-Key agar Anda bisa mengulang request ini tanpa membuat transkripsi baru:

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 merespons dengan 201. Objeknya memiliki status awaiting_upload dan blok upload:

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

Server menentukan pembagian chunk, masing-masing sekitar 8 MiB (8.388.608 byte). Daftarnya tersedia di chunks; contoh di atas disingkat. Jaga kerahasiaan X-Upload-Token. Token ini hanya berlaku untuk unggahan tersebut selama 1 jam, sampai waktu pada expires_at.

2. Kirim chunk sesuai daftar

Untuk setiap chunk, ganti {index} pada chunk_url_template dengan nilai index, lalu kirim lewat PUT. Baca data file mulai dari offset sebanyak size byte dan kirim sebagai application/octet-stream. Ukurannya harus persis sesuai daftar server. Gunakan header X-Upload-Token untuk autentikasi, bukan Authorization.

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

Setelah menerima chunk, API merespons dengan { "object": "upload_chunk", "index": 0, "size": 8388608 }. Jika Anda mengirim ulang chunk yang sama, data sebelumnya diganti. Ukuran yang tidak sesuai atau indeks di luar daftar mendapat 422 invalid_request. Tanpa token yang masih berlaku, responsnya 401 unauthorized.

3. Lanjutkan unggahan yang terputus

Panggil GET /v1/transcriptions/:id/upload untuk memeriksa data yang sudah diterima server:

{
  "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"
}

Periksa received_chunks, lalu kirim hanya chunk yang belum tercantum. Jika token sudah kedaluwarsa, ulangi request pada langkah 1 dengan Idempotency-Key dan parameter yang sama. Anda akan mendapat transkripsi yang sama beserta token unggahan baru.

4. Gabungkan file dan mulai transkripsi

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

Endpoint POST /v1/transcriptions/:id/upload/complete memeriksa kelengkapan dan ukuran semua chunk. Setelah itu, server menggabungkan file dan memasukkan transkripsi ke antrean. Responsnya 202 beserta objek transkripsi.

Jika ada chunk yang belum diterima, API mengirim 409 upload_incomplete. Kirim ulang chunk dengan indeks yang tercantum di missing_chunks. Jika unggahan sudah selesai atau dibatalkan, responsnya 409 invalid_state. Untuk mengikuti proses transkripsi, lakukan polling lewat GET /v1/transcriptions/:id?wait=60 atau gunakan webhook.

Jalankan seluruh alur dengan Python

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"])

Batas unggahan dan masa penyimpanan

• Satu tim bisa membuka maksimal 20 sesi unggahan berstatus awaiting_upload sekaligus. Jika menambah sesi di atas batas itu, API mengirim 429 too_many_active_jobs dengan header Retry-After.
• Selesaikan unggahan dalam 24 jam sejak sesi dibuat. Setelah itu, sesi dibatalkan dan semua chunk dihapus.
• File media dihapus 24 jam setelah status transkripsi menjadi completed, failed, atau canceled. Transkrip tetap tersimpan sampai Anda menghapusnya lewat DELETE /v1/transcriptions/:id.
• Jika transkripsi gagal atau dibatalkan, Anda tidak membayar. Penghitungan biaya dilakukan setelah durasi file diketahui: per menit rekaman, dibulatkan ke atas. Baca biaya dan batas penggunaan.