Bagaimana cara menghubungkan API Tencent Hunyuan Hy4? Jalankan permintaan pertama dengan OpenAI SDK dan perkirakan biayanya

Bagaimana cara menghubungkan API Tencent Hunyuan Hy4? Jalankan permintaan pertama dengan OpenAI SDK dan perkirakan biayanya

Ringkasan: Artikel ini menggunakan OpenAI Python SDK untuk memanggil API Tencent Hunyuan Hy4 dengan mode non-streaming, menjalankan permintaan teks murni pertama sampai berhasil, serta menjelaskan cara memverifikasi hasil, memperkirakan biaya, memeriksa tagihan, dan menangani error umum.

Jawaban langsung: API Tencent Hunyuan Hy4 dapat diakses melalui antarmuka kompatibel OpenAI milik APIYI. Siapkan tiga konfigurasi berikut untuk mengirim permintaan pertama:

  • Kunci API: Buat di api.apiyi.com/token, lalu simpan di variabel lingkungan APIYI_API_KEY.
  • Base URL SDK: https://api.apiyi.com/v1.
  • ID model: hy4.

Endpoint HTTP yang sesuai adalah POST https://api.apiyi.com/v1/chat/completions. Per 2026-11-21, harga Hy4 dalam tabel harga per satu juta token adalah: input tanpa cache (cache miss) $0.85, output $2.55, pembacaan cache $0.045. Penagihan aktual mengacu pada tabel harga APIYI di docs.apiyi.com/models (kategori Tencent).

Garis waktu: Tencent merilis versi resmi Hy4 pada 4 November, dan membuka bobot model pada 20 November. APIYI sudah menyediakan model ini sebelum bobot dibuka; pengumuman peluncurannya dapat dilihat di docs.apiyi.com/news/hy4-launch. Pengumuman itu sudah memuat contoh streaming, jadi artikel ini hanya membahas empat hal lainnya: pemanggilan non-streaming, verifikasi hasil, pemeriksaan tagihan, dan troubleshooting kegagalan. Pengumuman menyebutkan bahwa Hy4 mendukung input gambar; artikel ini hanya mendemonstrasikan teks murni. Video, antarmuka Responses, dan Computer Use tidak termasuk dalam cakupan artikel ini, dan tidak ada data pengujian aktual di dalam artikel.

tencent-hunyuan-hy4-api-openai-sdk-first-request-cost-id-image-0

Peta Pengetahuan dan Urutan Membaca untuk Integrasi API Tencent Hunyuan Hy4

Seluruh proses terbagi dalam empat langkah; hasil dari langkah sebelumnya menjadi masukan untuk langkah berikutnya. Sebaiknya baca sesuai urutan nomor. Bagian 4 dapat dirujuk terpisah saat terjadi error.

Langkah Bagian terkait Mengapa ditempatkan di sini Kriteria penerimaan
Menyiapkan permintaan 1.1, 1.2 Jika endpoint, nama model, dan Key salah, langkah berikutnya akan gagal SDK dapat diimpor, variabel environment dapat membaca Key, dan tidak ada Key plaintext di dalam kode
Panggilan pertama 2.1, 2.2 Gunakan dulu teks pendek tanpa data pelanggan untuk memastikan jalur sudah terhubung Konten yang dikembalikan adalah “产品=混元、版本=Hy4”, tidak terpotong, serta usage dan request ID tersimpan
Mencocokkan tagihan 3.1, 3.2 Setelah jalur terhubung, perkirakan biaya untuk menilai apakah volume panggilan dapat diperbesar Nilai perkiraan dapat dicocokkan item per item dengan log konsumsi di konsol
Troubleshooting kegagalan 4 Saat langkah mana pun gagal, tentukan penyebabnya berdasarkan kode error dan body error Dapat membedakan kesalahan konfigurasi, masalah izin, rate limit, dan timeout, serta menentukan apakah dapat dicoba ulang

tencent-hunyuan-hy4-api-openai-sdk-first-request-cost-id-image-1

Perlu Diketahui: Istilah Terkait API Hy4

Istilah Penjelasan singkat
Non-streaming (stream=False) Model mengembalikan hasil lengkap sekaligus setelah generasi selesai, sehingga lebih mudah memeriksa konten dan penggunaan secara keseluruhan
finish_reason Alasan generasi kali ini berakhir. stop berarti selesai normal, length berarti mencapai batas panjang dan terpotong
usage Field penggunaan token dalam respons; yang umum adalah prompt_tokens (input) dan completion_tokens (output)
request ID Identitas satu permintaan, digunakan untuk menemukan panggilan ini di log. Tidak setiap respons selalu menyertakannya
Pembacaan cache Bagian input yang mengenai cache, ditagih dengan harga pembacaan cache tersendiri
Grup (Default/SVIP) Grup tempat token berada; menentukan model mana yang dapat dipanggil oleh token ini

1. Menyiapkan Permintaan API Tencent Hunyuan Hy4

1.1 Mengonfigurasi Model Hy4 dan Endpoint

Cek dulu satu per satu setiap item konfigurasi. Sebagian besar kegagalan pada pemanggilan pertama justru terjadi di langkah ini.

Item konfigurasi Nilai Keterangan
SDK base_url https://api.apiyi.com/v1 Tulis hanya sampai /v1, SDK akan menambahkan /chat/completions secara otomatis
Endpoint HTTP POST https://api.apiyi.com/v1/chat/completions Gunakan alamat ini kalau mengirim permintaan HTTP langsung tanpa SDK
Model ID hy4 Nama model versi resmi, isi persis dalam huruf kecil
Grup yang tersedia Default, SVIP Grup tempat token berada harus mencakup Hy4
Mode output stream=False Sepanjang artikel ini memakai mode non-streaming

Kesalahan yang paling umum adalah memasukkan endpoint lengkap ke dalam base_url. SDK akan menyambung /chat/completions sekali lagi di belakang alamat tersebut, sehingga path-nya jadi dobel dan akhirnya mengembalikan 404. Penjelasan lengkap antarmuka kompatibel bisa dilihat di docs.apiyi.com/api-capabilities/openai/compatible.

1.2 Memasang OpenAI SDK dan Menyimpan Key dengan Aman

Alamat proyek SDK Python resmi ada di github.com/openai/openai-python. Sebaiknya pasang di dalam virtual environment supaya tidak bentrok versi dengan paket yang sudah ada di sistem:

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
python -m pip install openai

Key dibuat di api.apiyi.com/token. Saat membuatnya, pastikan grup tempat token berada bisa memanggil Hy4. Setelah Key didapat, tulis ke variabel lingkungan terminal yang sedang dipakai, jangan ditaruh di file kode:

export APIYI_API_KEY="token-anda"     # Windows PowerShell: $env:APIYI_API_KEY="token-anda"

Perhatikan beberapa hal berikut saat mengelola Key:

  • Kode hanya membaca Key dari os.environ['APIYI_API_KEY']. Kalau variabel lingkungan belum diset, pakai input interaktif getpass; teks yang diketik tidak akan tampil di layar.
  • Kalau menyimpan Key di file .env, masukkan file itu ke .gitignore supaya tidak ter-commit ke repo.
  • Kalau Key muncul di screenshot, log, atau tiket, ganti dulu dengan mask seperti sk-***.

Verifikasi: jalankan di terminal python -c "import openai, os; print(openai.__version__, bool(os.environ.get('APIYI_API_KEY')))". Kalau muncul nomor versi dan True, berarti langkah ini selesai.

2. Mengirim permintaan Hy4 pertama dengan OpenAI SDK

2.1 Contoh Python non-streaming lengkap

Permintaan pertama ini hanya melakukan satu hal sederhana: mengekstrak nama produk dan nomor versi dari sebuah kalimat publik, tanpa menyertakan data pelanggan apa pun. Desain ini punya dua keuntungan. Pertama, outputnya sangat pendek sehingga biayanya rendah. Kedua, jawabannya unik sehingga mudah dinilai benar atau salah.

import os
import re
from getpass import getpass
from openai import OpenAI

key = os.environ.get("APIYI_API_KEY") or getpass("输入 APIYI_API_KEY:")

PROMPT = "仅从这句话提取产品和版本:腾讯混元 Hy4 正式版已上线。请只写一行:产品=…;版本=…"

with OpenAI(
    base_url="https://api.apiyi.com/v1",   # Antarmuka kompatibel OpenAI APIYI
    api_key=key,
    timeout=60.0,
    max_retries=0,                         # Matikan percobaan ulang otomatis; jika gagal, manusia yang memutuskan apakah akan mengirim ulang
) as client:
    result = client.chat.completions.create(
        model="hy4",
        messages=[{"role": "user", "content": PROMPT}],
        stream=False,
    )

request_id = getattr(result, "_request_id", None)
print("request_id:", request_id if request_id else "响应未提供")

if not result.choices:
    raise SystemExit("未通过:choices 为空,没有返回正文")

choice = result.choices[0]
content = (choice.message.content or "").strip()
print("finish_reason:", choice.finish_reason)
print("content:", content)

usage = getattr(result, "usage", None)
prompt_tokens = getattr(usage, "prompt_tokens", None) if usage else None
completion_tokens = getattr(usage, "completion_tokens", None) if usage else None
print("prompt_tokens:", prompt_tokens if prompt_tokens is not None else "缺失(不按 0 处理)")
print("completion_tokens:", completion_tokens if completion_tokens is not None else "缺失(不按 0 处理)")


def accept(text: str, finish_reason) -> tuple[bool, str]:
    if not text:
        return False, "正文为空"
    if finish_reason == "length":
        return False, "输出被截断"
    t = re.sub(r"\s+", "", text)
    t = t.replace(":", "=").replace(":", "=").replace(";", ";")
    prod = re.search(r"产品=([^;\n]+)", t)
    ver = re.search(r"版本=([^;\n]+)", t)
    if not prod or not ver:
        return False, "缺少产品或版本字段"
    strip_punct = lambda s: re.sub(r"[。..,,、!!??\"“”'‘’]", "", s)
    if "混元" not in strip_punct(prod.group(1)):
        return False, f"产品值错误:{prod.group(1)}"
    if strip_punct(ver.group(1)) != "Hy4":
        return False, f"版本值错误:{ver.group(1)}"
    return True, "通过"


ok, reason = accept(content, choice.finish_reason)
print("验收:", reason)

Beberapa pengaturan dalam contoh ini perlu dijelaskan:

  • max_retries=0 mematikan percobaan ulang otomatis dari SDK. Bagian 4 akan membahas bahwa setelah timeout, server mungkin sudah menyelesaikan permintaan; pengiriman ulang otomatis dapat menyebabkan penagihan ganda, jadi keputusan untuk mencoba ulang harus diambil oleh manusia.
  • Pernyataan with akan menutup koneksi setelah pemanggilan selesai.
  • Saat field usage tidak ada, kode secara eksplisit mencetak “缺失”, bukan memperlakukannya sebagai 0, agar biaya tidak terlewat saat penghitungan di kemudian hari.

Penjelasan lebih lanjut tentang struktur respons dapat dilihat di docs.apiyi.com/api-capabilities/openai/response-handling.

2.2 Kriteria penerimaan untuk permintaan Hy4 pertama

Saat penerimaan, hanya periksa dua field di dalam message.content: nilai field 产品 mengandung “混元”, dan nilai field 版本 adalah “Hy4”. Perbedaan titik dua, titik koma, serta tanda baca akhir kalimat dalam bentuk lebar penuh atau setengah lebar dapat diterima. Berikut satu baris output yang memenuhi persyaratan, ini adalah format ilustrasi, bukan respons aktual hasil pengujian:

产品=腾讯混元;版本=Hy4

Situasi berikut semuanya dinilai tidak lulus; jangan meloloskannya hanya karena “terlihat mirip”:

Situasi Hasil Alasan
choices kosong, atau content berupa string kosong Tidak lulus Tidak memperoleh konten utama, berarti jalur pemrosesan belum benar-benar berjalan
finish_reason bernilai length Tidak lulus Output terpotong, hasil tidak lengkap
Versi ditulis sebagai Hy3, Hunyuan, atau nilai lain Tidak lulus Nilai field salah
Hanya berbeda pada tanda baca, spasi, atau titik dua lebar penuh/setengah lebar Lulus Termasuk perbedaan format yang diizinkan

Setelah lulus penerimaan, catat request ID (jika ada dalam respons), waktu permintaan, nama model, prompt_tokens, dan completion_tokens. Informasi ini akan digunakan saat memeriksa tagihan di bagian 3.2.

3. Estimasi dan Verifikasi Biaya API Hy4

3.1 Estimasi Satu Tugas Batch Berdasarkan Tabel Harga

Input pada permintaan pertama sangat singkat, biayanya bisa diabaikan, sehingga tidak banyak gunanya untuk mengestimasikan biaya darinya. Berikut kita ganti dengan skenario hipotetis yang tidak berkaitan dengan permintaan singkat contoh: suatu tugas memasukkan 100 ribu token, semuanya tidak mengenai cache, dan mengeluarkan 20 ribu token. Input dan output dihitung masing-masing berdasarkan harga satuannya:

Item Penagihan Asumsi Penggunaan Harga Satuan (per juta token) Biaya
Input tidak mengenai cache 100,000 $0.85 $0.085
Output 20,000 $2.55 $0.051
Total — — $0.136

Proses perhitungannya adalah 0.1 × 0.85 + 0.02 × 2.55 = 0.136. Ada dua hal yang perlu diperhatikan saat mengestimasikan:

  • Harga satuan output adalah 3 kali harga satuan input yang tidak mengenai cache. Untuk tugas dengan volume output besar, biaya terutama ditentukan oleh output.
  • Jika completion_tokens sudah mencakup bagian pemikiran model, jangan tambahkan biaya pemikiran secara terpisah, jika tidak akan terjadi penghitungan ganda.

3.2 Membedakan Bucket Cache dari Log Konsumsi Aktual

“Pembacaan cache” adalah bagian penagihan tersendiri, tetapi cara pemisahan field pada respons yang berbeda belum tentu sama, sehingga tidak ada nama field yang berlaku umum yang dapat menjamin hasilnya akurat. Cara yang andal adalah memastikan terlebih dahulu di tagihan: apakah token yang mengenai cache sudah dihitung dalam total input.

Jika tagihan memastikan bagian cache sudah termasuk dalam total input, kurangi satu kali bagian cache dari total input, lalu hitung masing-masing. Berikut melanjutkan asumsi 3.1, dan selanjutnya mengasumsikan bahwa dari 100 ribu input, 40 ribu mengenai cache:

Item Penagihan Asumsi Penggunaan Harga Satuan (per juta token) Biaya
Input tidak mengenai cache 60,000 $0.85 $0.051
Pembacaan cache 40,000 $0.045 $0.0018
Output 20,000 $2.55 $0.051
Total — — $0.1038

tencent-hunyuan-hy4-api-openai-sdk-first-request-cost-id-image-2

Nilai estimasi hanya dapat dijadikan referensi, yang final adalah log konsumsi. Cara memverifikasi adalah dengan menyaring catatan yang sesuai di konsol api.apiyi.com/log:

  1. Persempit rentang berdasarkan waktu permintaan.
  2. Jika respons menyediakan request ID, gunakan untuk menentukan secara tepat permintaan ini.
  3. Pastikan modelnya adalah hy4, token sama dengan token yang benar-benar digunakan kode.
  4. Bandingkan penggunaan input, cache, output dan jumlah pemotongan biaya dalam log, lihat apakah sesuai dengan nilai estimasi.

Arti spesifik dari field log dapat dilihat di docs.apiyi.com/faq/log-billing-explained.

4. Penanganan Kesalahan API Hy4

Saat melakukan troubleshooting, periksa dulu kode status HTTP, lalu baca informasi spesifik di dalam badan kesalahan. Hanya melihat kode status saja mudah menimbulkan kesalahan penilaian—misalnya, kode 429 yang sama bisa memiliki penyebab yang sangat berbeda. Pada permintaan asli di Bagian 2.1, tangkap exception SDK: untuk timeout koneksi lihat APITimeoutError, untuk kegagalan koneksi lainnya lihat APIConnectionError; saat menerima respons kesalahan, catat status_code, request_id, dan badan kesalahan dari APIStatusError. Nilailah dulu hasil permintaan yang ada, baru kemudian putuskan apakah perlu mencoba ulang; lakukan desensitisasi pada badan kesalahan sebelum memberikan umpan balik. Urutan penanganannya sebagai berikut:

Kesalahan Periksa terlebih dahulu Apakah perlu mencoba ulang
401 Apakah Key benar, apakah sudah kedaluwarsa, dan apakah base_url adalah https://api.apiyi.com/v1 Jangan coba ulang sebelum konfigurasi diperbaiki
403 Tentukan dari badan kesalahan apakah ini masalah izin grup, pastikan grup tempat token berada mencakup Hy4 Jangan coba ulang sebelum izin diperbaiki
404 Apakah path menggandakan /chat/completions, apakah nama model adalah hy4 Jangan coba ulang sebelum konfigurasi diperbaiki
429 Tentukan dari badan kesalahan apakah ini pembatasan laju sementara atau kuota tidak cukup Pembatasan laju sementara dapat dicoba ulang dengan backoff terbatas; jika kuota tidak cukup, perlu isi ulang atau sesuaikan kuota
Kesalahan koneksi Apakah jaringan, proxy, DNS normal, serta apakah protokol dan domain base_url benar Dapat dicoba ulang setelah jaringan pulih
Timeout Cari dulu berdasarkan waktu di api.apiyi.com/log untuk memastikan apakah permintaan sudah dieksekusi Jika sudah dieksekusi jangan kirim ulang; jika belum, coba lagi

Perlu penjelasan khusus untuk dua kasus, 429 dan timeout:

  • Backoff dan coba ulang untuk 429: hanya berlaku untuk pembatasan laju sementara. Jumlah percobaan ulang harus diberi batas atas, dan interval setiap kali diperpanjang secara bertahap. Jika kuota tidak cukup, berapa kali pun mencoba ulang tidak akan berhasil.
  • Timeout: Klien tidak menerima respons dalam 60 detik bukan berarti server tidak memproses permintaan tersebut. Jika server sudah selesai memproses, mengirim ulang langsung akan mengeksekusi sekali lagi, dan biaya juga akan terpotong sekali lagi. Jadi sebaiknya periksa log terlebih dahulu, pastikan permintaan belum dieksekusi, baru kemudian kirim ulang.

Jika perlu menghubungi dukungan teknis, sebelum mengirim, lakukan desensitisasi dulu terhadap informasi sensitif seperti Key dan data pelanggan di badan kesalahan dan log, lalu lampirkan kode status, waktu permintaan, nama model, dan request ID. Cara penyimpanan dan pengiriman informasi kesalahan lihat di docs.apiyi.com/api-manual/error-reporting.

Setelah semua troubleshooting selesai, jalankan ulang dengan contoh pada 2.1; seluruh alur baru dianggap lulus jika memenuhi tiga syarat sekaligus:

  1. Fungsi penerimaan mengeluarkan “lulus”.
  2. finish_reason bukan length.
  3. Di log konsol dapat ditemukan catatan dengan waktu yang sama dan model hy4, serta penggunaan (usage) sesuai dengan usage yang dicatat secara lokal.

Similar Posts