Speech-to-Text / STT

Transcribe audio from a URL into text, with support for multiple languages, speaker diarization, custom vocabulary recognition, and audio/video format conversion. The Turing Platform uses an asynchronous task model: submit a task to receive a task_run_id, then poll for the result.

For the full service entry and billing details, see Audio Models → Speech-to-Text / ASR.

Why Asynchronous?

STT tasks take longer than chat responses — long audio files can take tens of seconds. Synchronous blocking increases client-side pressure. The async + polling model lets you:

• Avoid HTTP connection timeout limits
• Run multiple tasks concurrently in batch scenarios
• Transcribe long audio in the background while the frontend handles other work

Basic Usage

The /audio/transcriptions/runs endpoint accepts a JSON request body. Specify the audio source via the file field: set file.type to public_uri and file.file_uri to a publicly accessible audio URL.

1. Submit a Task

curl "$TURING_BASE_URL/audio/transcriptions/runs" \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_name": "aliyun/tingwu",
    "language_code": "cn",
    "file": {
      "type": "public_uri",
      "file_uri": "https://example.com/speech.mp3"
    },
    "diarization": {
      "enabled": true,
      "speaker_number": 2
    },
    "turing_options": {
      "include_service_usages": true
    }
  }'

Response:

{
  "code": 0,
  "message": "Success",
  "data": {
    "task_run_id": "run_xxx",
    "task_run_state": "running"
  }
}

2. Poll for Status

curl "$TURING_BASE_URL/audio/transcriptions/runs/run_xxx" \
  -H "Authorization: Bearer $TURING_API_KEY"

The task state transitions from running to completed or failed.

On success:

{
  "code": 0,
  "message": "Success",
  "data": {
    "task_run_id": "run_xxx",
    "task_run_state": "completed",
    "transcript": "Full transcription text...",
    "segments": [
      {
        "start_time": 0,
        "end_time": 3200,
        "text": "First segment",
        "words": []
      }
    ],
    "audio_info": {
      "duration_ms": 42300
    }
  }
}

Python Example

import time

import httpx

BASE = "https://live-turing.cn.llm.tcljd.com/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}


def transcribe(audio_url: str) -> dict:
    create_resp = httpx.post(
        f"{BASE}/audio/transcriptions/runs",
        headers={**headers, "Content-Type": "application/json"},
        json={
            "service_name": "aliyun/tingwu",
            "language_code": "cn",
            "file": {
                "type": "public_uri",
                "file_uri": audio_url,
            },
            "diarization": {
                "enabled": True,
                "speaker_number": 2,
            },
            "turing_options": {
                "include_service_usages": True,
            },
        },
        timeout=30,
    )
    create_resp.raise_for_status()
    task_id = create_resp.json()["data"]["task_run_id"]

    while True:
        status_resp = httpx.get(f"{BASE}/audio/transcriptions/runs/{task_id}", headers=headers, timeout=30)
        status_resp.raise_for_status()
        body = status_resp.json()["data"]
        if body["task_run_state"] in {"completed", "failed"}:
            return body
        time.sleep(2)

Parameters

Parameter	Description	Value
service_name	Transcription service	Use aliyun/tingwu
language_code	Target language	e.g. cn / en / ja
file.type	Audio source type	Use public_uri
file.file_uri	Public audio URL	https://example.com/speech.mp3
diarization.enabled	Enable speaker diarization	true / false
diarization.speaker_number	Number of speakers	Positive integer, optional
phrase_set	Custom vocabulary for recognition	Names, product names, brand names, etc.
extra	Advanced configuration	e.g. audio/video format conversion settings
turing_options.include_service_usages	Return billing details	true / false

Audio/Video Format Conversion Example

To convert audio or video to a specific format before transcription, pass conversion settings in extra:

{
  "extra": {
    "Parameters": {
      "Transcoding": {
        "TargetAudioFormat": "mp3",
        "TargetVideoFormat": "mp4"
      }
    }
  }
}

Supported Formats

mp3, mp4, mpeg, mpga, m4a, wav, webm.

Billing

Billed by audio duration (per second); rates vary slightly between Chinese and multilingual modes. See Billing & Usage for details.

FAQ

• How do I specify the model? Use service_name to select the transcription service. For audio transcription, pass aliyun/tingwu.
• Task stuck in running → The transcription service is still processing. For high-volume scenarios, use exponential backoff when polling.
• Poor custom vocabulary recognition → Use phrase_set to provide names, product names, brand names, and other terms to improve recognition accuracy.

See Also

• Realtime Voice — Bidirectional real-time conversation (does not use the task model)
• Multimodal Input — Use audio as chat input with GPT-4o / Qwen
• Audio Models → Speech-to-Text / ASR — Meeting transcription ASR service entry
• TTS — The reverse: synthesize text into speech