DeepScript

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.1

Co 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 z curlcURL
# 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"
Node.js z fetchJavaScript
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);
Python z requestsPython
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. 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. 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. 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. 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.

DeepScript REST API – Speech-to-Text z Niemiec | DeepScript