Integracja
REST API do transkrypcji – trzy wywołania i gotowe
Wyślij, odpytuj, odbierz wynik. JSON, znaczniki czasu dla słów, 99 języków, własne serwery w Niemczech.
API DeepScript działa według klasycznego wzorca zadania asynchronicznego: wysyłasz metodą POST plik audio lub wideo na `/v1/transcriptions`, otrzymujesz identyfikator zadania, a następnie odpytujesz `/v1/transcriptions/{id}` co kilka sekund albo otrzymujesz powiadomienie przez webhook. Uwierzytelnianie odbywa się przez nagłówek `X-API-KEY`; klucze zaczynają się od `ds_live_` i generuje się je w panelu. Odpowiedź zawiera pełny tekst, znaczniki czasu dla słów z wartościami confidence, wykryty język, etykiety mówców oraz obliczony koszt. Formaty eksportu (TXT, SRT, VTT, JSON) pobierasz przez `/v1/transcriptions/{id}/export?format=srt`. Pełna specyfikacja OpenAPI 3.1 znajduje się pod `/openapi.json`, interaktywny interfejs Scalar pod `/docs`.
Zobacz specyfikację OpenAPI 3.1Co możesz zbudować
- Wysyłaj pliki audio i wideo do 500 MB (mp3, wav, flac, ogg, m4a, aac, mp4, mkv, webm, mov).
- Dokładne znaczniki czasu na poziomie słów z wartością confidence dla każdego słowa – idealne do napisów i integracji z edytorami.
- Diaryzacja mówców w obu wariantach, optymalizacja dialektów DACH w modelu Premium.
- Custom Vocabulary na żądanie – nazwy firm, terminy medyczne i nazwy własne są poprawnie rozpoznawane.
- Formaty eksportu na żądanie: TXT, SRT, VTT, JSON. Bez ponownego kodowania po stronie klienta.
- Wywołania zwrotne webhook przy `transcription.completed` – polling jest opcjonalny, long-polling niepotrzebny.
Przykłady kodu
# Upload an audio file and start a Premium transcription job
curl -X POST https://api.deepscript.com/v1/transcriptions \
-H "X-API-KEY: ds_live_xxx" \
-F "file=@meeting.mp3" \
-F "model=premium" \
-F "language=de"
# Response:
# {
# "id": "8b1f2e4a-9c3d-4f7e-a1b2-1234567890ab",
# "status": "queued",
# "progress": 0,
# "model": "premium",
# "createdAt": "2026-06-09T10:14:22Z"
# }
# Poll until done
curl https://api.deepscript.com/v1/transcriptions/8b1f2e4a-9c3d-4f7e-a1b2-1234567890ab \
-H "X-API-KEY: ds_live_xxx"
# Download as SRT
curl -o meeting.srt \
"https://api.deepscript.com/v1/transcriptions/8b1f2e4a-9c3d-4f7e-a1b2-1234567890ab/export?format=srt" \
-H "X-API-KEY: ds_live_xxx"import { readFile } from "node:fs/promises";
const API_KEY = process.env.DEEPSCRIPT_API_KEY; // "ds_live_xxx"
const BASE = "https://api.deepscript.com/v1";
async function transcribe(filePath) {
const buffer = await readFile(filePath);
const blob = new Blob([buffer], { type: "audio/mpeg" });
const form = new FormData();
form.append("file", blob, "meeting.mp3");
form.append("model", "premium");
form.append("language", "de");
const created = await fetch(`${BASE}/transcriptions`, {
method: "POST",
headers: { "X-API-KEY": API_KEY },
body: form,
}).then((r) => r.json());
// Poll every 3 seconds until done
while (true) {
await new Promise((r) => setTimeout(r, 3000));
const job = await fetch(`${BASE}/transcriptions/${created.id}`, {
headers: { "X-API-KEY": API_KEY },
}).then((r) => r.json());
if (job.status === "completed") return job.result;
if (job.status === "failed") throw new Error(job.errorMessage);
}
}
const result = await transcribe("./meeting.mp3");
console.log(result.text);import os
import time
import requests
API_KEY = os.environ["DEEPSCRIPT_API_KEY"] # "ds_live_xxx"
BASE = "https://api.deepscript.com/v1"
HEADERS = {"X-API-KEY": API_KEY}
def transcribe(path: str) -> dict:
with open(path, "rb") as f:
created = requests.post(
f"{BASE}/transcriptions",
headers=HEADERS,
files={"file": f},
data={"model": "premium", "language": "de"},
timeout=120,
).json()
job_id = created["id"]
while True:
time.sleep(3)
job = requests.get(
f"{BASE}/transcriptions/{job_id}", headers=HEADERS, timeout=30
).json()
if job["status"] == "completed":
return job["result"]
if job["status"] == "failed":
raise RuntimeError(job["errorMessage"])
result = transcribe("meeting.mp3")
print(result["text"])Konfiguracja w kilku krokach
- 1
Wygeneruj klucz API
Wygeneruj klucz w panelu w Ustawienia → Bezpieczeństwo. Klucz wyświetla się tylko raz i zaczyna się od `ds_live_`. Zapisz go w aplikacji jako zmienną środowiskową `DEEPSCRIPT_API_KEY`.
- 2
Wyślij żądanie uploadu
Upload multipart na POST `/v1/transcriptions` z polami `file`, `model` (standard/premium) oraz opcjonalnie `language` (ISO 639-1) i `vocabularyId`. Natychmiast otrzymujesz identyfikator zadania (HTTP 202).
- 3
Odpytuj lub czekaj na webhook
Wywołuj GET `/v1/transcriptions/{id}` co 2-5 sekund albo zarejestruj webhook na `transcription.completed`. Zasada ogólna: 1 minuta audio = 5-15 sekund przetwarzania w Standard, nieco dłużej w Premium.
- 4
Pobierz lub wyeksportuj wynik
Gdy `status: 'completed'`, pole `result` zawiera pełny tekst, słowa ze znacznikami czasu i etykiety mówców. Aby wyeksportować SRT/VTT/TXT/JSON: GET `/v1/transcriptions/{id}/export?format=srt`.
Często zadawane pytania
Jakie są limity zapytań?
100 żądań na minutę na klucz API przy wywołaniach uwierzytelnionych, 30/min bez uwierzytelnienia. Odpowiedź zawiera nagłówki `X-RateLimit-Limit`, `X-RateLimit-Remaining` i `X-RateLimit-Reset`. Po przekroczeniu otrzymujesz HTTP 429 z nagłówkiem Retry-After.
Czy obsługujecie klucze idempotencji?
Tak – wyślij `Idempotency-Key: <uuid>` jako nagłówek przy POST `/v1/transcriptions`. Identyczne klucze w ciągu 24 godzin zwracają tę samą odpowiedź bez ponownego uruchamiania zadania. Zalecane przy ponawianiu w razie problemów sieciowych.
Jaki interwał pollingu zastosować?
Zalecamy 2-5 sekund. W przypadku dłuższych nagrań (>30 min) wystarczy co 10 sekund. Jeśli wolisz uniknąć pollingu, użyj webhooków (`/v1/webhooks`) lub strumienia Server-Sent Events pod `/v1/transcriptions/{id}/events`.
Co się dzieje przy nieudanym zadaniu?
Status zmienia się na `failed`, a pole `errorMessage` zawiera ciąg Problem Details zgodny z RFC 7807. Częste przyczyny: zbyt krótki plik (<1 s), brak wykrywalnego dźwięku, nieobsługiwany format. Za nieudane zadania nie pobieramy opłat.
Czy istnieje oficjalny SDK?
Na razie udostępniamy specyfikację OpenAPI 3.1 pod `/openapi.json` – za pomocą `openapi-generator-cli` lub `openapi-typescript` wygenerujesz typowanego klienta w dowolnym języku. Oficjalne SDK dla TypeScript i Python są w przygotowaniu.
Gotowy, aby wdrożyć to na produkcję?
Załóż konto, wygeneruj klucz API i działaj. Trzy transkrypcje za darmo na test. Pełna dokumentacja OpenAPI 3.1 pod api.deepscript.com/docs.