Skip to main content

音声・動画翻訳

qwen3-livetranslate-flash は、OpenAI 互換のチャット補完エンドポイントを通じて音声および動画を翻訳します。すべてのリクエストはストリーミングされます。

注: DashScope インターフェイスはサポートされていません。

サポートされるモデル

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

前提条件

開始する前に、以下の手順を完了してください。
  1. API キーの作成
  2. API キーを環境変数として設定
  3. OpenAI SDK のインストール（Python または Node.js 向け）

エンドポイント

POSThttps://WorkspaceId.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions
POSThttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions

リージョンSDK base_urlHTTP エンドポイント
シンガポールhttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
北京https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Model Studio では、シンガポールリージョン向けにワークスペース専用ドメインがリリースされました：https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com。この新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。https://dashscope-intl.aliyuncs.com から新しいドメインへの移行を推奨します。{WorkspaceId} はご利用のワークスペース ID です。これは Model Studio コンソールの ワークスペース詳細 ページで確認できます。既存のドメインは引き続き完全に機能します。

クイックスタート

以下の例では、音声ファイルを翻訳し、ストリーミングにより翻訳テキストとオーディオの両方を返します。中国 (北京) リージョンを使用する場合は、base_url を置き換えてください。

Python 

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    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,
    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 

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"
    }
  }'

動画入力

音声ではなく動画を翻訳するには、コンテンツタイプを 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"
                },
            }
        ],
    },
]
その他のパラメーターはすべて同じです。

リクエストボディ

必須パラメーター

パラメータータイプ説明
modelstringモデル名。有効な値：qwen3-livetranslate-flash、qwen3-livetranslate-flash-2025-12-01。
messagesarrayメッセージの配列。ユーザーからのメッセージは 1 つだけサポートされます。
streambooleantrue である必要があります。デフォルトは false ですが、ストリーミング出力のみがサポートされているため、この値を true に設定する必要があります。
translation_optionsobject翻訳構成。詳細については、「翻訳オプション」をご参照ください。これは標準的な OpenAI パラメーターではありません。Python SDK では extra_body 内で渡します。Node.js または HTTP の場合は、トップレベルで渡します。

オプションパラメーター

パラメータータイプデフォルト説明
modalitiesarray["text"]出力モダリティ。["text", "audio"] を設定するとテキストとオーディオの両方が返され、["text"] を設定するとテキストのみが返されます。
audioobject-出力オーディオの構成。modalities に "audio" が含まれる場合に必須です。詳細については、「オーディオ出力オプション」をご参照ください。
stream_optionsobject-ストリーミング構成。詳細については、「ストリームオプション」をご参照ください。
max_tokensintegerモデルの最大値生成するトークンの最大数。この制限に達するか、生成が完了すると停止します。
seedinteger-再現性のための乱数シード。同一のリクエストに対して同一のシードを指定すると、同一の出力が得られます。範囲：[0, 2^31-1]。
speech_ratefloat1.0出力オーディオの再生速度を制御します。1.0 が通常速度、1.0 未満が低速、1.0 より大きいと高速になります。範囲：[0.5, 2.0]。

サンプリングパラメーター

翻訳精度を確保するため、これらのパラメーターはデフォルト値のままにしてください。
パラメータータイプデフォルト範囲備考
temperaturefloat0.000001[0, 2)出力の多様性を制御します。
top_pfloat0.8(0, 1.0]ヌクレウスサンプリングのしきい値。
presence_penaltyfloat0[-2.0, 2.0]正の値を設定すると、繰り返しを抑制します。
top_kinteger1>= 0候補セットのサイズ。None または 100 を超える値を指定すると、top_k は無効化され、top_p のみが有効になります。標準的な OpenAI パラメーターではありません。Python SDK では extra_body を使用します。
repetition_penaltyfloat1.05> 0繰り返しシーケンスにペナルティを課します。標準的な OpenAI パラメーターではありません。Python SDK では extra_body を使用します。

メッセージオブジェクト

messages 配列には、role が user に設定されたオブジェクトが 1 つだけ含まれている必要があります。 content 配列のアイテムのプロパティ：
フィールドタイプ必須説明
typestringはいinput_audio、動画入力の場合は video_url。
input_audioobjecttype が input_audio音声入力。以下を参照してください。
video_urlobjecttype が video_url動画入力。以下を参照してください。
input_audio オブジェクト：
フィールドタイプ必須説明
datastringはい音声ファイルの URL または Base64 データ URL。ローカルファイルの場合は、「Base64 エンコードされたローカルファイルの入力」をご参照ください。
formatstringはい音声フォーマット（例：mp3、wav）。
video_url オブジェクト：
フィールドタイプ必須説明
urlstringはい動画ファイルの公開 URL または Base64 データ URL。ローカルファイルの場合は、「Base64 エンコードされたローカルファイルの入力」をご参照ください。

翻訳オプション

フィールドタイプ必須説明
source_langstringいいえソース言語の英語フルネーム。「サポートされる言語」をご参照ください。省略した場合、言語は自動検出されます。
target_langstringはいターゲット言語の英語フルネーム。「サポートされる言語」をご参照ください。
注: translation_options は標準的な OpenAI パラメーターではありません。Python SDK では extra_body 内で渡します。Node.js または HTTP の場合は、リクエストボディのトップレベルで渡します。 
extra_body={"translation_options": {"source_lang": "zh", "target_lang": "en"}}

オーディオ出力オプション

modalities が ["text", "audio"] の場合に必須です。
フィールドタイプ必須説明
voicestringはい出力オーディオの音声。「サポートされる音声」をご参照ください。
formatstringはい出力オーディオフォーマット。wav のみがサポートされています。

ストリームオプション

フィールドタイプデフォルト説明
include_usagebooleanfalsetrue の場合、最終チャンクにトークン使用量の詳細が含まれます。

応答

API は一連のストリーミングチャンクを返します。各チャンクは chat.completion.chunk オブジェクトとして返されます。チャンクは、テキスト、オーディオ、トークン使用量の 3 種類に分類されます。

テキストチャンク

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"
}

オーディオチャンク

choices[0].delta.audio.data に増分的な Base64 エンコードされたオーディオが含まれます。 
{
  "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"
}

トークン使用量チャンク

include_usage が true の場合、最終チャンクとして返されます。choices 配列は空となり、usage にトークンの内訳が含まれます。 
{
  "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
    }
  }
}
注: 動画入力の場合、prompt_tokens_details.audio_tokens には動画から抽出されたオーディオトークンが含まれます。video_tokens には動画固有のトークン数が報告されます。

応答フィールド

フィールドタイプ説明
idstringリクエスト識別子。すべてのチャンクで同一です。
choicesarray生成されたコンテンツ。最終的な使用量チャンクでは空です。
choices[].delta.contentstring増分的な翻訳テキスト。オーディオチャンクでは null です。
choices[].delta.audioobject増分的なオーディオデータ。テキストチャンクでは null です。
choices[].delta.audio.datastringBase64 エンコードされたオーディオセグメント。
choices[].delta.audio.idstring出力オーディオの一意な識別子。
choices[].delta.audio.expires_atintegerリクエストが作成されたタイムスタンプ。
choices[].delta.rolestringメッセージロール。最初のチャンクでのみ存在します。
choices[].finish_reasonstringstop、max_tokens によって切り捨てられた場合は length、処理中の場合は null です。
choices[].indexinteger常に 0 です。
createdintegerリクエストの UNIX タイムスタンプ。すべてのチャンクで同一です。
modelstringモデル名。
objectstring常に chat.completion.chunk です。
usageobjectinclude_usage が true の場合に、最終チャンクでのみ存在します。
usage.prompt_tokensinteger入力トークンの合計数。
usage.completion_tokensinteger出力トークンの合計数。
usage.total_tokensintegerprompt_tokens と completion_tokens の合計。
usage.completion_tokens_details.audio_tokensinteger出力オーディオトークン。
usage.completion_tokens_details.text_tokensinteger出力テキストトークン。
usage.prompt_tokens_details.audio_tokensinteger入力オーディオトークン。動画入力の場合、動画から抽出されたオーディオが含まれます。
usage.prompt_tokens_details.text_tokensinteger入力テキストトークン。常に 0 です。
usage.prompt_tokens_details.video_tokensinteger入力動画トークン。動画入力の場合にのみ存在します。

null 固定フィールド

OpenAI との互換性のために応答に含まれていますが、常に null を返すフィールドは以下のとおりです。 reasoning_content、function_call、refusal、tool_calls、logprobs、service_tier、system_fingerprint

注意事項

  • ストリーミングのみ。 stream を true に設定してください。非ストリーミング呼び出しはサポートされていません。
  • 単一メッセージ。 messages 配列にはユーザーからのメッセージを 1 つだけ受け付けます。
  • 非標準パラメーター。 translation_options、top_k、および repetition_penalty は標準的な OpenAI API には含まれていません。Python SDK では extra_body で渡します。Node.js/HTTP の場合は、トップレベルに含めてください。
  • サンプリングのデフォルト値。 temperature、top_p、top_k、presence_penalty、および repetition_penalty のデフォルト値は翻訳精度のために最適化されています。これらの値を変更すると、品質が低下する可能性があります。
  • 出力オーディオフォーマット。 wav のみがサポートされています。
  • 自動言語検出。 source_lang を省略すると、入力言語が自動検出されます。

参考資料