Whisper-1 API: twoja pierwsza transkrypcja audio

Pierwsze żądanie Whisper-1 API wymaga pliku audio, jawnego ID modelu i formatu wyniku. W SeedRouter przesyłasz nagranie, zapisujesz zwrócone ID zadania, a następnie pobierasz transkrypcję po jego ukończeniu. Zacznij od krótkiego nagrania, którego słowa już znasz: łatwiej zauważysz braki słów i nietypową pisownię.

Ten przewodnik korzysta z asynchronicznego kontraktu SeedRouter. Nie jest synchronicznym przykładem OpenAI SDK, którego można użyć bez zmian. Strona modelu Whisper-1 zawiera Playground i aktualną cenę; dokumentacja API opisuje każde pole i nierozstrzygnięte testy zgodności. ^[1]

Przygotuj jedno nagranie

Użyj mowy, którą masz prawo przetwarzać. Krótki WAV lub MP3 to dobry początek. Obecny limit przesyłania wynosi 26,214,400 bajtów; plik musi zawierać czytelne audio o mierzalnym czasie. Rozszerzenie .mp3 nie czyni pliku tekstowego ze zmienioną nazwą poprawnym audio. Dokumentacja oddziela dziewięć udokumentowanych formatów wejścia od tych, które przeszły rzeczywiste testy. ^[1]

Poniższe nagranie to oryginalna syntetyczna mowa po angielsku, przygotowana do tego poradnika. Jego przebieg fali znajduje się na okładce. Cytowane zdanie na okładce pochodzi ze scenariusza nagrania i nie jest deklaracją dokładności.

Pobierz próbkę o długości 10,31 sekundy. Scenariusz brzmi: “This is a sample recording for an audio transcription tutorial. Our meeting starts at nine thirty on Monday. Please bring the project notes and review the final checklist before we begin.”

Przechowuj klucz API w zmiennej środowiskowej po stronie serwera. Nie umieszczaj go na publicznej stronie, w paczce aplikacji mobilnej ani na udostępnionym zrzucie ekranu. Poniższy przykład w Pythonie używa requests i odczytuje SEEDROUTER_API_KEY ze środowiska.

Wyślij żądanie Whisper-1 API raz

Dla pierwszego żądania wybierz json. Możesz wtedy odczytać pole text pobranego pliku bez obsługi kodów czasu napisów. Część multipart file musi zawierać rzeczywiste bajty; podanie URL jako jej wartości nie jest równoważne przesłaniu pliku. Pozwól klientowi ustawić typ treści i separator multipart. ^[1]

Zapisz to jako transcribe.py. Skrypt zapisuje znacznik wysłania przed POST, a po nim ID przyjętego zadania. Ponowne uruchomienie odczytuje istniejące zadanie. Jeśli wynik POST jest niepewny, znacznik powstrzymuje skrypt przed przypadkowym utworzeniem duplikatu.

import json
import os
from pathlib import Path

import requests

base = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
state = Path("whisper-task.json")
audio = Path("recording.wav")

if not state.exists():
    if not 0 < audio.stat().st_size <= 26_214_400:
        raise ValueError("Choose a nonempty recording within the upload limit")
    with state.open("x") as marker:
        json.dump({"status": "submission_unconfirmed"}, marker)
    with audio.open("rb") as recording:
        response = requests.post(
            f"{base}/audio/transcriptions",
            headers=headers,
            files={"file": (audio.name, recording, "audio/wav")},
            data={"model": "whisper-1", "response_format": "json"},
            timeout=180,
            allow_redirects=False,
        )
    response.raise_for_status()
    accepted = response.json()
    task_id = accepted.get("id")
    if not isinstance(task_id, str) or not task_id.startswith("task_"):
        raise RuntimeError("Submission could not be confirmed; check task history")
    state.write_text(json.dumps({"id": task_id}), encoding="utf-8")

saved = json.loads(state.read_text(encoding="utf-8"))
if "id" not in saved:
    raise RuntimeError("Check task history before submitting another recording")

response = requests.get(
    f"{base}/tasks/{saved['id']}", headers=headers, timeout=30,
    allow_redirects=False,
)
response.raise_for_status()
task = response.json()
print(task["status"])
if task["status"] == "completed":
    result = requests.get(task["output"]["url"], timeout=60)
    result.raise_for_status()
    print(result.json()["text"])
elif task["status"] == "failed":
    print(task["error"])

Uruchom python transcribe.py. Jeśli wypisze processing, odczekaj kilka sekund i uruchom to samo polecenie ponownie. Odczyta zapisane ID zamiast ponownie przesyłać plik. Zapisuj osobny plik stanu dla każdego świadomie nowego nagrania. Samo przekroczenie czasu klienta nie oznacza niepowodzenia zadania.

Odczytaj ukończoną transkrypcję

Odpowiedź przyjęcia zawiera id, model, status i created_at. Ukończenie dodaje output.url i output.format. Ten URL wskazuje plik wyniku; nie jest zadaniem generowania mediów wymagającym kolejnego płatnego żądania. GET pobiera plik. ^[1]

Czytaj słowa podczas słuchania nagrania. Sprawdź nazwy, liczby i granice zdań przed użyciem tekstu jako napisów lub dokładnego cytatu. Transkrypcja jest szkicem wypowiedzi, a znaczniki czasu nie usuwają potrzeby jej weryfikacji.

Lokalne testy od początku do końca z 19 października 2026 r. ukończyły wszystkie pięć formatów transkrypcji i tłumaczenie z angielskim wejściem. Potwierdzają one sposób dostarczania i rozliczania przetestowanych nagrań. Nie określają procentowej dokładności ani jakości tłumaczenia między językami.

Wybierz tekst, znaczniki czasu lub napisy

Dla znaczników czasu słów wyślij response_format=verbose_json oraz powtarzane pole multipart timestamp_granularities[] o wartości word. Dodaj kolejną część z wartością segment, jeśli potrzebujesz obu. W Pythonowym requests użyj listy par (name, value) dla powtarzanych pól. Każdy znacznik czasu jest w sekundach. ^[2]

Znaczniki czasu słów i etykiety mówców to różne wyniki. Whisper-1 nie zamienia spotkania w transkrypcję z etykietami mówców tylko dlatego, że zażądasz segmentów. Nie przesyła też częściowego tekstu strumieniowo: stream jest ignorowane dla tego modelu. Pomiń chunking_strategy dla zweryfikowanego wariantu; jawny wybór auto nie przeszedł rzeczywistego testu zgodności. ^[1]

W razie potrzeby dodaj język i kontekst pisowni

Opcjonalne language=en informuje żądanie transkrypcji, że wejście jest po angielsku. Pomiń je, gdy chcesz wykrywania. Jeśli nazwę produktu łatwo źle usłyszeć, umieść jej poprawną pisownię w prompt, w języku audio. Prompt Whisper dostarcza kontekst; nie działa jak instrukcja czatu, która niezawodnie narzuca określony układ. ^[3]

Utrzymuj kontekst związany z fragmentem. Whisper uwzględnia tylko ostatnie 224 tokeny własnego tokenizera. Wysłanie długiego dokumentu nie daje nagraniu nieograniczonego słownika, a liczenie znaków nie jest wiarygodnym zamiennikiem tej reguły tokenów.

Dla tłumaczenia na angielski zmień punkt końcowy na /audio/translations. Jego pięć pól żądania to file, model, prompt, response_format i temperature. Tłumaczenie tworzy angielski tekst; nie ma wyboru języka docelowego. Jeśli podajesz prompt, użyj angielskiego. ^[4]

Sprawdź koszt przed rozszerzeniem procesu

Poniższa aktualna tabela używa zmierzonego czasu audio. Dłuższa transkrypcja nie zwiększa opłaty za czas tego samego nagrania. Czas każdego pliku jest zaokrąglany w górę do pełnych sekund, a potem przeliczany na jednostki pomiaru audio. Dokumentacja API zawiera dokładny wzór, a Playground pokazuje szacunek po odczytaniu czasu nagrania. Nieudane żądania nie są płatne.

Przed przetwarzaniem wielu plików sprawdź jedno reprezentatywne nagranie i obejrzyj wynik. Zachowaj ID zadania każdego nagrania, aby odzyskać stan po przerwaniu połączenia przez odczyt istniejącego zadania. Przed dodaniem napisów lub mniej przetestowanych kombinacji formatów zobacz pełną dokumentację parametrów.

Pytania przy pierwszej integracji

Czy mogę użyć przykładu OpenAI Python SDK bez zmian?

Nie. Pola wejściowe multipart są znajome, ale SeedRouter zwraca asynchroniczne ID zadania. Synchroniczny klient oczekujący text w odpowiedzi POST wymaga dostosowania. Ten przykład pokazuje jawnie wysłanie i odczyt wyniku.

Dlaczego w moim wyniku JSON nie ma znaczników czasu słów?

Domyślny format json to odpowiedź skupiona na tekście. Zażądaj razem verbose_json i szczegółowości znaczników czasu word. Sam czas segmentów nie tworzy wpisu dla każdego słowa.

Czy wysłać kolejny POST po przekroczeniu czasu?

Najpierw sprawdź zapisane ID zadania lub historię zadań. Odpowiedź mogła zaginąć po przyjęciu. Odczyt istniejącego zadania pozwala uniknąć tworzenia kolejnego żądania dla tego samego nagrania.

Czy Whisper-1 jest wycofywany?

OpenAI ogłosiło wyłączenie Whisper w swoim API 26 lutego 2027 r. Ten komunikat nie określa daty wyłączenia tej usługi. Budując nową integrację, uwzględnij komunikaty o cyklu życia na liście czynności utrzymaniowych. ^[5]

Źródła

[1] Dokumentacja SeedRouter Whisper-1 API i stan weryfikacji, sprawdzono 19 października 2026 r.

[2] Dokumentacja transkrypcji OpenAI.

[3] Przewodnik OpenAI po promptach Whisper.

[4] Dokumentacja tłumaczenia OpenAI.

[5] Komunikat OpenAI o wycofaniu modeli transkrypcji.