> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Pobierz lub wyeksportuj transkrypcję projektu
> Pobierz oryginalną lub przetłumaczoną transkrypcję w formacie JSON, SRT lub VTT, z opcjonalnymi etykietami mówców.
Pobierz oryginalną lub przetłumaczoną transkrypcję w formacie JSON, SRT lub VTT, z opcjonalnymi etykietami mówców.
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/transcripts_get
```
## Uwierzytelnianie i uprawnienia
Wyślij klucz API VoiceCheap w tym nagłówku. Obsługiwany jest również nagłówek Authorization: Bearer z tym samym kluczem API. Tokeny dostępu OAuth są
akceptowane tylko przez MCP, a nie przez ten endpoint REST.
Wymagane uprawnienia: `transcription:read`.
Wymagana jest aktywna płatna subskrypcja. Uprawnienia nie zmieniają ról w zespole, własności zasobów, kredytów na multimedia ani limitów planu.
## Parametry
Wartość tekstowa.
Minimalna długość: 1. Maksymalna długość: 200. Wzorzec: `^[^/\\]+$`.
Wartość tekstowa.
Dozwolone wartości: "original", "translated". Wartość domyślna: "original".
Wartość tekstowa.
Dozwolone wartości: "afrikaans", "albanian", "amharic", "arabic", "armenian", "assamese", "azerbaijani", "basque", "belarusian", "bengali", "bosnian", "bulgarian", "catalan", "croatian", "czech", "danish", "dutch", "english", "british english", "estonian", "finnish", "french", "french canadian", "galician", "german", "greek", "gujarati", "hebrew", "hindi", "hungarian", "icelandic", "indonesian", "irish", "italian", "japanese", "kannada", "kazakh", "khmer", "korean", "lao", "latvian", "lithuanian", "macedonian", "malay", "malayalam", "mandarin", "marathi", "mongolian", "nepali", "norwegian", "persian", "polish", "portuguese", "brazilian portuguese", "pt\_brazil", "punjabi", "romanian", "russian", "serbian", "slovak", "slovenian", "spanish", "swahili", "swedish", "tagalog", "tamil", "telugu", "thai", "turkish", "ukrainian", "urdu", "vietnamese", "welsh", "yoruba", "zulu".
Wartość tekstowa.
Dozwolone wartości: "json", "srt", "vtt". Wartość domyślna: "json".
Wartość logiczna.
Wartość domyślna: false.
Poniższy JSON Schema zachowuje dokładne nazwy pól, typy zagnieżdżone, wartości domyślne, ograniczenia i akceptowane wartości udostępniane przez mechanizm wykrywania. Dodatkowe reguły zależności między polami znajdują się w uwagach do operacji.
```json theme={null}
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"source": {
"default": "original",
"type": "string",
"enum": ["original", "translated"]
},
"targetLanguage": {
"type": "string",
"enum": [
"afrikaans",
"albanian",
"amharic",
"arabic",
"armenian",
"assamese",
"azerbaijani",
"basque",
"belarusian",
"bengali",
"bosnian",
"bulgarian",
"catalan",
"croatian",
"czech",
"danish",
"dutch",
"english",
"british english",
"estonian",
"finnish",
"french",
"french canadian",
"galician",
"german",
"greek",
"gujarati",
"hebrew",
"hindi",
"hungarian",
"icelandic",
"indonesian",
"irish",
"italian",
"japanese",
"kannada",
"kazakh",
"khmer",
"korean",
"lao",
"latvian",
"lithuanian",
"macedonian",
"malay",
"malayalam",
"mandarin",
"marathi",
"mongolian",
"nepali",
"norwegian",
"persian",
"polish",
"portuguese",
"brazilian portuguese",
"pt_brazil",
"punjabi",
"romanian",
"russian",
"serbian",
"slovak",
"slovenian",
"spanish",
"swahili",
"swedish",
"tagalog",
"tamil",
"telugu",
"thai",
"turkish",
"ukrainian",
"urdu",
"vietnamese",
"welsh",
"yoruba",
"zulu"
]
},
"outputFormat": {
"default": "json",
"type": "string",
"enum": ["json", "srt", "vtt"]
},
"includeSpeakerLabels": {
"default": false,
"type": "boolean"
}
},
"required": ["projectId"],
"additionalProperties": false
}
```
## Przykłady żądań
Zastąp przykładowe identyfikatory zasobów i klucze multimediów wartościami zwróconymi dla Twojego konta. Przy ponawianiu tej samej operacji zmieniającej dane zachowaj identyfikator żądania.
```bash cURL theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/transcripts_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","source":"original","outputFormat":"json","includeSpeakerLabels":false}'
```
```javascript JavaScript theme={null}
const input = {
projectId: 'project_launch_2026',
source: 'original',
outputFormat: 'json',
includeSpeakerLabels: false,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/transcripts_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/transcripts_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "source": "original", "outputFormat": "json", "includeSpeakerLabels": False},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
```
## Odpowiedź
Pierwsze pomyślne wykonanie zwraca HTTP 200 z wynikiem operacji w data. Ponowienie może zamiast tego zwrócić zapisany stan żądania. Przykład przedstawia jedną obsługiwaną odpowiedź, bez wszystkich opcjonalnych pól.
Zwraca sformatowany obiekt transkrypcji. JSON zawiera format, transcript i contentType; SRT/VTT zawierają również content i fileExtension.
```json HTTP 200 theme={null}
{
"data": {
"format": "json",
"transcript": {
"source": "original",
"language": "fr",
"duration": 75,
"text": "Bienvenue au lancement.",
"speakers": [
{
"id": 0,
"label": "Speaker 1"
}
],
"segments": [
{
"index": 0,
"text": "Bienvenue au lancement.",
"begin": 0,
"end": 2,
"duration": 2,
"speaker": 0,
"language": "fr"
}
]
},
"contentType": "application/json"
}
}
```
## Pola wyniku
| Pole | Opis |
| - | - |
| `data.format` | json, srt lub vtt. |
| `data.contentType` | application/json, application/x-subrip; charset=utf-8 lub text/vtt; charset=utf-8. |
| `data.content` | Tekst napisów wyłącznie dla srt/vtt. |
| `data.fileExtension` | srt lub vtt wyłącznie dla eksportu tekstu. |
| `data.transcript.source` | original lub translated. |
| `data.transcript.language` | Język transkrypcji. |
| `data.transcript.duration` | Większa z wartości: zapisany czas trwania multimediów lub czas końca ostatniego segmentu, w sekundach. |
| `data.transcript.text` | Połączony niepusty tekst segmentów. |
| `data.transcript.speakers` | Unikalni mówcy posortowani według liczbowego id, z wygenerowanymi etykietami Speaker N. |
| `data.transcript.segments` | Znormalizowane segmenty posortowane według begin i index, z polami index, text, begin, end, duration, speaker, language oraz opcjonalnymi confidence, finalSpeedFactor, words. |
| `data.transcript.workId` | Dołączane dla przetłumaczonej transkrypcji. |
| `data.transcript.targetLanguage` | Dołączane dla przetłumaczonej transkrypcji. |
| `data.transcript.segments[].begin` | Czas rozpoczęcia w sekundach, ujednolicony do trzech miejsc po przecinku. |
| `data.transcript.segments[].end` | Czas zakończenia w sekundach, ujednolicony do trzech miejsc po przecinku. |
| `data.transcript.segments[].duration` | Dodatni czas trwania segmentu w sekundach. |
| `data.transcript.segments[].speaker` | Numer mówcy liczony od zera. |
| `data.transcript.segments[].finalSpeedFactor` | Opcjonalny iloraz czasu trwania przetłumaczonej mowy i przedziału czasu jej segmentu, zaokrąglony do trzech miejsc po przecinku; wartości powyżej 1 wskazują, że mowa wymagała przyspieszenia. |
## outputFormat srt; source translated, targetLanguage english, includeSpeakerLabels true.
Zwraca przetłumaczoną transkrypcję i treść SRT z prefiksami mówców.
```json HTTP 200 theme={null}
{
"data": {
"format": "srt",
"transcript": {
"source": "translated",
"language": "english",
"duration": 75,
"text": "Welcome to the product launch.",
"speakers": [
{
"id": 0,
"label": "Speaker 1"
}
],
"segments": [
{
"index": 0,
"text": "Welcome to the product launch.",
"begin": 0,
"end": 2,
"duration": 2,
"speaker": 0,
"language": "english",
"finalSpeedFactor": 1.08
}
],
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"targetLanguage": "english"
},
"content": "1\n00:00:00,000 --> 00:00:02,000\nSpeaker 1: Welcome to the product launch.\n",
"contentType": "application/x-subrip; charset=utf-8",
"fileExtension": "srt"
}
}
```
## outputFormat vtt; source translated, targetLanguage english, includeSpeakerLabels true.
Zwraca przetłumaczoną transkrypcję i zawartość WEBVTT z etykietami głosów.
```json HTTP 200 theme={null}
{
"data": {
"format": "vtt",
"transcript": {
"source": "translated",
"language": "english",
"duration": 75,
"text": "Welcome to the product launch.",
"speakers": [
{
"id": 0,
"label": "Speaker 1"
}
],
"segments": [
{
"index": 0,
"text": "Welcome to the product launch.",
"begin": 0,
"end": 2,
"duration": 2,
"speaker": 0,
"language": "english",
"finalSpeedFactor": 1.08
}
],
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"targetLanguage": "english"
},
"content": "WEBVTT\n\n1\n00:00:00.000 --> 00:00:02.000\nWelcome to the product launch.\n",
"contentType": "text/vtt; charset=utf-8",
"fileExtension": "vtt"
}
}
```
## Uwagi do operacji
* source ma domyślnie wartość original, outputFormat — json, a includeSpeakerLabels — false. Przetłumaczone źródło wymaga targetLanguage.
* W przypadku przetłumaczonych transkrypcji wybierana jest najnowsza wersja językowa pasująca do targetLanguage. Ta akcja nie przyjmuje workId ani translatedVersionId jako danych wejściowych.
* Eksporty SRT i VTT pozostają wynikami akcji w formacie JSON: content zawiera tekst napisów, a transcript pozostaje dostępny w tym samym obiekcie. Ta procedura obsługi nie zwraca surowej odpowiedzi do pobrania.
* includeSpeakerLabels wpływa tylko na wpisy eksportu tekstowego: SRT używa prefiksów Speaker N:, a VTT używa znaczników głosu.
* Zapisane słowa transkrypcji, jeśli istnieją, udostępniają index, text, speaker i opcjonalnie confidence; znaczniki czasu na poziomie słów nie są tworzone sztucznie. Przetłumaczone segmenty mogą udostępniać finalSpeedFactor, gdy istnieją dane czasowe wygenerowanej mowy.
## Wykorzystanie
Każde pomyślne wywołanie zużywa jedno wywołanie z miesięcznego limitu API/MCP. Obowiązują również kredyty na multimedia oraz limity generowania danej operacji.
## Błędy
| Status HTTP | Kod | Znaczenie lub sposób rozwiązania |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Dane uwierzytelniające zostały podane w parametrze zapytania access\_token lub api\_key. Wysyłaj dane uwierzytelniające w nagłówkach. |
| 400 | `VALIDATION_ERROR` | Popraw dane wejściowe zgodnie ze schematem. Nieprawidłowe lub niespójne wartości są odrzucane przed wykonaniem. |
| 401 | `API_KEY_EXPIRED` | Klucz API wygasł. |
| 401 | `INVALID_API_KEY` | Podaj prawidłowy, niewygasły klucz API. |
| 401 | `INVALID_CREDENTIAL` | Nagłówek Authorization ma nieprawidłowy format lub jest sprzeczny z x-api-key. |
| 401 | `MISSING_CREDENTIAL` | Nie podano użytecznych danych uwierzytelniających w nagłówku lub przekroczyły one 4096 znaków. |
| 401 | `USER_NOT_FOUND` | Konto powiązane z poświadczeniem już nie istnieje. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | Użytkownik, do którego należą dane uwierzytelniające, należy do więcej niż jednego zespołu, więc kontekst rozliczeniowy jest niejednoznaczny. |
| 403 | `FORBIDDEN` | Uwierzytelniony podmiot wykonujący akcję nie ma dostępu do tego projektu. |
| 403 | `INSUFFICIENT_SCOPE` | Nadaj wszystkie wymagane uprawnienia lub wybierz inne dane uwierzytelniające. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Nie udało się zweryfikować limitów integracji konta. |
| 403 | `SUBSCRIPTION_REQUIRED` | Użyj aktywnej płatnej subskrypcji. |
| 403 | `TEAM_OWNER_NOT_FOUND` | Nie znaleziono konta faktycznego właściciela zespołu. |
| 404 | `PROJECT_NOT_FOUND` | Projekt nie istnieje na dostępnym koncie. |
| 404 | `TRANSCRIPT_NOT_FOUND` | Nie istnieje użyteczna transkrypcja dla żądanego źródła i języka docelowego. |
| 409 | `TRANSCRIPT_NOT_READY` | Żądana oryginalna lub przetłumaczona transkrypcja jest nadal przetwarzana. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Poczekaj na odnowienie miesięcznego limitu lub zmień plan. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Jeśli występuje nagłówek Retry-After, odczekaj wskazany czas i stosuj rosnące odstępy między ponowieniami. |
| 500 | `INTERNAL_ERROR` | Sprawdź stan zapisanego żądania i historię zasobu przed podjęciem decyzji o ponowieniu operacji zmieniającej dane. |
| 503 | `SERVER_RESTARTING` | Serwer jest uruchamiany ponownie. Spróbuj ponownie wkrótce i zachowaj ten sam identyfikator żądania dla operacji zmieniającej dane. |
```json theme={null}
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["transcription:read"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.