Transkrip YouTube di C# dengan HttpClient dan Records

Dari dotnet run hingga transkrip tercetak membutuhkan waktu sekitar dua detik di mesin saya, dan sebagian besar itu adalah putaran jaringan. Tidak ada paket NuGet yang muncul di mana pun dalam posting ini — mendapatkan transkrip YouTube di C# adalah satu permintaan GET, dan HttpClient plus System.Text.Json telah dikirim dalam kotak selama bertahun-tahun. Di akhir Anda akan memiliki aplikasi konsol lengkap dengan tipe record untuk respons, Main asinkron, dan penanganan kesalahan yang membaca objek kesalahan terstruktur API alih-alih menebak dari kode status.

Tiga records

API mengembalikan {"result": {...}} pada sukses dan {"error": {...}} pada kegagalan, jadi modelkan amplop secara langsung:

public record Transcript(
    string VideoId,
    string Title,
    string PubDate,
    string Content,
    int ContentSize,
    bool Truncated);

public record ApiError(
    string Code,
    string Message,
    int Status,
    int? RetryAfterSeconds);

public record Envelope(Transcript? Result, ApiError? Error);

Satu panggilan Deserialize<Envelope> menangani setiap respons. Properti mana pun yang bukan nol adalah jawaban Anda. RetryAfterSeconds dapat dibatalkan karena hanya kesalahan batas laju yang membawanya.

Program

Target .NET 8, bekerja sebagaimana mestinya di 6 dan 7:

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

public static class Program
{
    private static readonly HttpClient Http = new();
    private static readonly JsonSerializerOptions Json =
        new(JsonSerializerDefaults.Web);

    public static async Task Main(string[] args)
    {
        var videoUrl = args.Length > 0
            ? args[0]
            : "https://www.youtube.com/watch?v=dQw4w9WgXcQ";

        var request = new HttpRequestMessage(HttpMethod.Get,
            "https://youtube2text.org/api/transcribe" +
            $"?url={Uri.EscapeDataString(videoUrl)}&maxChars=40000");
        request.Headers.Add("x-api-key",
            Environment.GetEnvironmentVariable("YT2TEXT_KEY"));

        var response = await Http.SendAsync(request);
        var envelope = JsonSerializer.Deserialize<Envelope>(
            await response.Content.ReadAsStringAsync(), Json);

        if (envelope?.Error is { } err)
        {
            Console.Error.WriteLine($"{err.Code}: {err.Message}");
            if (err.RetryAfterSeconds is int wait)
                Console.Error.WriteLine($"Retry after {wait}s");
            Environment.Exit(1);
        }

        var t = envelope!.Result!;
        Console.WriteLine($"{t.Title} ({t.ContentSize} chars, truncated: {t.Truncated})");
        Console.WriteLine(t.Content[..Math.Min(t.Content.Length, 400)]);
    }
}

JsonSerializerDefaults.Web memetakan bidang camelCase API ke properti record PascalCase, jadi tidak ada atribut [JsonPropertyName] tunggal di tempat yang terlihat. Parameter url menerima setiap varian URL YouTube ditambah id 11 karakter bare, dan header dapat berupa Authorization: Bearer yt_... alih-alih x-api-key jika itu cocok dengan middleware Anda lebih baik.

Tentang maxChars=40000

maxChars membatasi panjang transkrip; 150000 adalah default dan batas keras. Jika caption video berjalan melampaui batas Anda, Truncated kembali true dan Anda mendapatkan N karakter pertama — jadi periksa flag sebelum mengasumsikan Anda memiliki teks lengkap. Saya menetapkan 40000 dalam contoh karena transkrip ini biasanya berakhir dalam prompt LLM, dan pada kasar empat karakter per token itu adalah anggaran 10k token. Jika panggilan model Anda melalui Responses API OpenAI, ada cara untuk melewati pipa HTTP sepenuhnya melalui server MCP dengan OpenAI; setara Anthropic ada dalam menggunakan transkrip dengan Claude API.

Kode kesalahan untuk cabang

ApiError.Code adalah string stabil: UNAUTHORIZED (401), VALIDATION_ERROR dan INVALID_URL (400), VIDEO_NOT_FOUND dan TRANSCRIPT_UNAVAILABLE (404), RATE_LIMIT_EXCEEDED (429), YOUTUBE_ERROR (500). Yang mengejutkan orang-orang adalah TRANSCRIPT_UNAVAILABLE: transkrip berasal dari trek caption YouTube, dan video yang pemiliknya menonaktifkan caption tidak memiliki apa pun untuk dikembalikan — tidak ada kebijakan retry yang memperbaikinya. Pola cocok pada kode, perlakukan sebagai lompatan permanen.

Untuk kunci uji tanpa signup, GET https://youtube2text.org/api/demo-key — kunci ini bersama dan dibatasi 5 video per bulan per IP, jadi hanya untuk eksperimen. Jika Go juga ada dalam tumpukan Anda, panggilan yang sama di Golang menggunakan trik amplop yang identik.

Referensi mesin yang dapat dibaca lengkap — setiap parameter, setiap kesalahan, siap untuk ditempel ke dalam prompt sistem — ada di youtube2text.org/api.md.