Referensi API untuk qwen3-livetranslate-flash - Alibaba Cloud Model Studio

qwen3-livetranslate-flash menerjemahkan audio dan video melalui titik akhir chat completions yang kompatibel dengan OpenAI. Semua permintaan dikirimkan secara streaming.

Catatan: Antarmuka DashScope tidak didukung.

Model yang didukung

qwen3-livetranslate-flash
qwen3-livetranslate-flash-2025-12-01

Prasyarat

Sebelum memulai, lengkapi langkah-langkah berikut:

Buat Kunci API
Konfigurasikan Kunci API sebagai variabel lingkungan
Instal SDK OpenAI (untuk Python atau Node.js)

Titik akhir

Wilayah	SDK `base_url`	Titik akhir HTTP
Singapura	`https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`	`POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions`
Beijing	`https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`	`POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions`

PentingModel Studio telah merilis domain khusus ruang kerja untuk wilayah Singapura: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami menyarankan Anda bermigrasi dari https://dashscope-intl.aliyuncs.com ke domain baru ini.

{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan di halaman Detail Ruang Kerja pada Konsol Model Studio. Domain lama tetap berfungsi sepenuhnya.

Mulai cepat

Contoh berikut menerjemahkan file audio dan mengembalikan teks serta audio terjemahan melalui streaming. Ganti base_url jika Anda menggunakan wilayah Beijing.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Berikut ini adalah URL wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung wilayah.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3-livetranslate-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250211/tixcef/cherry.wav",
                        "format": "wav",
                    },
                }
            ],
        }
    ],
    modalities=["text", "audio"],
    audio={"voice": "Cherry", "format": "wav"},
    stream=True,
    stream_options={"include_usage": True},
    extra_body={"translation_options": {"source_lang": "zh", "target_lang": "en"}},
)

for chunk in completion:
    print(chunk)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    // Berikut ini adalah URL wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung wilayah.
    baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});

async function main() {
    const completion = await client.chat.completions.create({
        model: "qwen3-livetranslate-flash",
        messages: [
            {
                role: "user",
                content: [
                    {
                        type: "input_audio",
                        input_audio: {
                            data: "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250211/tixcef/cherry.wav",
                            format: "wav",
                        },
                    },
                ],
            },
        ],
        modalities: ["text", "audio"],
        audio: { voice: "Cherry", format: "wav" },
        stream: true,
        stream_options: { include_usage: true },
        translation_options: { source_lang: "zh", target_lang: "en" },
    });

    for await (const chunk of completion) {
        console.log(JSON.stringify(chunk));
    }
}

main();

curl

## Berikut ini adalah URL wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung wilayah.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-livetranslate-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_audio",
            "input_audio": {
              "data": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250211/tixcef/cherry.wav",
              "format": "wav"
            }
          }
        ]
      }
    ],
    "modalities": ["text", "audio"],
    "audio": {
      "voice": "Cherry",
      "format": "wav"
    },
    "stream": true,
    "stream_options": {
      "include_usage": true
    },
    "translation_options": {
      "source_lang": "zh",
      "target_lang": "en"
    }
  }'

Input video

Untuk menerjemahkan video alih-alih audio, atur tipe konten menjadi video_url:

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "video_url",
                "video_url": {
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4"
                },
            }
        ],
    },
]

Semua parameter lain tetap sama.

Isi permintaan

Parameter wajib

Parameter	Tipe	Deskripsi
`model`	string	Nama model. Nilai yang valid: `qwen3-livetranslate-flash`, `qwen3-livetranslate-flash-2025-12-01`.
`messages`	array	Array pesan. Hanya satu pesan pengguna yang didukung.
`stream`	boolean	Harus diatur ke `true`. Nilai default-nya adalah `false`, tetapi hanya keluaran streaming yang didukung, sehingga Anda harus mengatur nilai ini ke `true`.
`translation_options`	object	Konfigurasi terjemahan. Lihat Opsi terjemahan. Ini adalah parameter non-standar OpenAI. Di SDK Python, masukkan dalam `extra_body`. Di Node.js atau HTTP, masukkan di tingkat atas badan permintaan.

Parameter opsional

Parameter	Tipe	Default	Deskripsi
`modalities`	array	`["text"]`	Modalitas keluaran. Atur ke `["text", "audio"]` untuk menerima keluaran teks dan audio, atau `["text"]` hanya untuk teks.
`audio`	object	-	Konfigurasi audio keluaran. Wajib saat `modalities` mencakup `"audio"`. Lihat Opsi keluaran audio.
`stream_options`	object	-	Konfigurasi streaming. Lihat Opsi streaming.
`max_tokens`	integer	Maksimum model	Jumlah maksimum token yang akan dihasilkan. Generasi berhenti pada batas ini atau ketika selesai.
`seed`	integer	-	Seed acak untuk reproduktibilitas. Seed yang sama menghasilkan keluaran identik untuk permintaan identik. Rentang: `[0, 2^31-1]`.
`speech_rate`	float	1.0	Mengontrol kecepatan audio keluaran. 1.0 adalah kecepatan normal, kurang dari 1.0 lebih lambat, lebih dari 1.0 lebih cepat. Rentang: [0.5, 2.0].

Parameter pengambilan sampel

Untuk akurasi terjemahan, pertahankan parameter-parameter ini pada nilai default-nya.

Parameter	Tipe	Default	Rentang	Catatan
`temperature`	float	0.000001	[0, 2)	Mengontrol keragaman keluaran.
`top_p`	float	0.8	(0, 1.0]	Ambang batas pengambilan sampel nucleus.
`presence_penalty`	float	0	[-2.0, 2.0]	Mengurangi pengulangan saat bernilai positif.
`top_k`	integer	1	>= 0	Ukuran kumpulan kandidat. Jika nilainya `None` atau lebih besar dari 100, `top_k` dinonaktifkan dan hanya `top_p` yang berlaku. Parameter non-standar OpenAI. SDK Python: gunakan `extra_body`.
`repetition_penalty`	float	1.05	> 0	Memberikan penalti pada urutan yang berulang. Parameter non-standar OpenAI. SDK Python: gunakan `extra_body`.

Objek pesan

Array messages harus berisi tepat satu objek dengan role diatur ke user.

Properti item array content:

Bidang	Tipe	Wajib	Deskripsi
`type`	string	Ya	`input_audio` untuk input audio, `video_url` untuk input video.
`input_audio`	object	Saat `type` adalah `input_audio`	Input audio. Lihat di bawah.
`video_url`	object	Saat `type` adalah `video_url`	Input video. Lihat di bawah.

Objek input_audio:

Bidang	Tipe	Wajib	Deskripsi
`data`	string	Ya	URL file audio, atau URL data Base64. Untuk file lokal, lihat Masukkan file lokal yang dikodekan Base64.
`format`	string	Ya	Format audio, seperti `mp3` atau `wav`.

Objek video_url:

Bidang	Tipe	Wajib	Deskripsi
`url`	string	Ya	URL publik file video, atau URL data Base64. Untuk file lokal, lihat Masukkan file lokal yang dikodekan Base64.

Opsi terjemahan

Bidang	Tipe	Wajib	Deskripsi
`source_lang`	string	Tidak	Nama lengkap bahasa sumber dalam bahasa Inggris. Lihat Bahasa yang didukung. Jika dihilangkan, bahasa akan dideteksi secara otomatis.
`target_lang`	string	Ya	Nama lengkap bahasa target dalam bahasa Inggris. Lihat Bahasa yang didukung.

Catatan: translation_options adalah parameter non-standar OpenAI. Di SDK Python, masukkan dalam extra_body. Di Node.js atau HTTP, masukkan di tingkat atas badan permintaan.

extra_body={"translation_options": {"source_lang": "zh", "target_lang": "en"}}

Opsi keluaran audio

Wajib saat modalities diatur ke ["text", "audio"].

Bidang	Tipe	Wajib	Deskripsi
`voice`	string	Ya	Suara untuk audio keluaran. Lihat Suara yang didukung.
`format`	string	Ya	Format audio keluaran. Hanya `wav` yang didukung.

Opsi streaming

Bidang	Tipe	Default	Deskripsi
`include_usage`	boolean	`false`	Saat diatur ke `true`, chunk terakhir mencakup detail penggunaan token.

Tanggapan

API mengembalikan serangkaian chunk streaming, masing-masing berupa objek chat.completion.chunk. Chunk dibagi menjadi tiga kategori: teks, audio, dan penggunaan token.

Chunk teks

Berisi teks terjemahan bertahap dalam choices[0].delta.content:

{
  "id": "chatcmpl-c22a54b8-40cc-4a1d-988b-f84cdf86868f",
  "choices": [
    {
      "delta": {
        "content": null,
        "role": null,
        "audio": {
          "data": "///+//7////+////////////AAAAAAAAAAABA......",
          "expires_at": 1764755440,
          "id": "audio_c22a54b8-40cc-4a1d-988b-f84cdf86868f"
        }
      },
      "finish_reason": null,
      "index": 0
    }
  ],
  "created": 1764755440,
  "model": "qwen3-livetranslate-flash",
  "object": "chat.completion.chunk"
}

Chunk audio

Berisi segmen audio bertahap yang dikodekan Base64 dalam choices[0].delta.audio.data:

{
  "id": "chatcmpl-c22a54b8-40cc-4a1d-988b-f84cdf86868f",
  "choices": [
    {
      "delta": {
        "content": null,
        "role": null,
        "audio": {
          "data": "///+//7////+////////////AAAAAAAAAAABA......",
          "expires_at": 1764755440,
          "id": "audio_c22a54b8-40cc-4a1d-988b-f84cdf86868f"
        }
      },
      "finish_reason": null,
      "index": 0
    }
  ],
  "created": 1764755440,
  "model": "qwen3-livetranslate-flash",
  "object": "chat.completion.chunk"
}

Chunk penggunaan token

Dikembalikan sebagai chunk terakhir saat include_usage diatur ke true. Array choices kosong, dan usage berisi rincian penggunaan token:

{
  "id": "chatcmpl-c22a54b8-40cc-4a1d-988b-f84cdf86868f",
  "choices": [],
  "created": 1764755440,
  "model": "qwen3-livetranslate-flash",
  "object": "chat.completion.chunk",
  "usage": {
    "completion_tokens": 242,
    "prompt_tokens": 415,
    "total_tokens": 657,
    "completion_tokens_details": {
      "accepted_prediction_tokens": null,
      "audio_tokens": 191,
      "reasoning_tokens": null,
      "rejected_prediction_tokens": null,
      "text_tokens": 51
    },
    "prompt_tokens_details": {
      "audio_tokens": 415,
      "cached_tokens": null,
      "text_tokens": 0,
      "video_tokens": null
    }
  }
}

Catatan: Untuk input video, prompt_tokens_details.audio_tokens mencakup token audio yang diekstraksi dari video. video_tokens melaporkan jumlah token khusus video.

Bidang tanggapan

Bidang	Tipe	Deskripsi
`id`	string	Pengidentifikasi permintaan. Identik di semua chunk.
`choices`	array	Konten yang dihasilkan. Kosong pada chunk penggunaan terakhir.
`choices[].delta.content`	string	Teks terjemahan bertahap. `null` pada chunk audio.
`choices[].delta.audio`	object	Data audio bertahap. `null` pada chunk teks.
`choices[].delta.audio.data`	string	Segmen audio yang dikodekan Base64.
`choices[].delta.audio.id`	string	Pengidentifikasi unik untuk audio keluaran.
`choices[].delta.audio.expires_at`	integer	Timestamp saat permintaan dibuat.
`choices[].delta.role`	string	Peran pesan. Hanya ada pada chunk pertama.
`choices[].finish_reason`	string	`stop` saat generasi selesai secara normal, `length` saat dipotong oleh `max_tokens`, `null` selama proses berlangsung.
`choices[].index`	integer	Selalu `0`.
`created`	integer	Timestamp Unix untuk permintaan. Identik di semua chunk.
`model`	string	Nama model.
`object`	string	Selalu `chat.completion.chunk`.
`usage`	object	Konsumsi token. Hanya ada pada chunk terakhir saat `include_usage` diatur ke `true`.
`usage.prompt_tokens`	integer	Total token input.
`usage.completion_tokens`	integer	Total token output.
`usage.total_tokens`	integer	Jumlah dari `prompt_tokens` dan `completion_tokens`.
`usage.completion_tokens_details.audio_tokens`	integer	Token audio output.
`usage.completion_tokens_details.text_tokens`	integer	Token teks output.
`usage.prompt_tokens_details.audio_tokens`	integer	Token audio input. Untuk input video, ini mencakup audio yang diekstraksi dari video.
`usage.prompt_tokens_details.text_tokens`	integer	Token teks input. Selalu `0`.
`usage.prompt_tokens_details.video_tokens`	integer	Token video input. Hanya ada untuk input video.

Bidang yang selalu bernilai null

Bidang-bidang berikut ada dalam tanggapan demi kompatibilitas OpenAI tetapi selalu mengembalikan null:

reasoning_content, function_call, refusal, tool_calls, logprobs, service_tier, system_fingerprint

Catatan penggunaan

Hanya streaming. Atur stream ke true. Panggilan non-streaming tidak didukung.
Pesan tunggal. Array messages hanya menerima satu pesan pengguna.
Parameter non-standar. translation_options, top_k, dan repetition_penalty tidak ada dalam API OpenAI standar. SDK Python: masukkan dalam extra_body. Node.js/HTTP: sertakan di tingkat atas.
Nilai default pengambilan sampel. Nilai default untuk temperature, top_p, top_k, presence_penalty, dan repetition_penalty telah dioptimalkan untuk akurasi terjemahan. Mengubahnya dapat menurunkan kualitas.
Format audio keluaran. Hanya wav yang didukung.
Deteksi bahasa otomatis. Jika source_lang dihilangkan, bahasa input akan dideteksi secara otomatis.

Referensi

Ikhtisar terjemahan audio dan video
Suara yang didukung
Bahasa yang didukung
Pemilihan model
Buat Kunci API
Konfigurasikan Kunci API sebagai variabel lingkungan
Instal SDK
Masukkan file lokal yang dikodekan Base64