Bangun Pipeline Audio-ke-Teks dengan API Pengenalan Ucapan - OpenSearch - Alibaba Cloud - OpenSearch

AI Search Open Platform menyediakan API pengenalan ucapan yang secara cepat mengonversi ucapan dari audio dan video menjadi teks terstruktur untuk transkripsi rapat, pengindeksan pencarian video, dan layanan pelanggan daring.

Daftar layanan

Nama layanan	ID layanan	Deskripsi	Batas QPS API
layanan pengenalan ucapan	ops-audio-asr-001	Menghasilkan subtitle dari konten audio.	5 Catatan Untuk meminta batas QPS API yang lebih tinggi, kirimkan tiket ke dukungan teknis.

Dapatkan kredensial autentikasi

Platform Terbuka AI Search memerlukan Kunci API untuk autentikasi. Untuk petunjuknya, lihat Dapatkan Kunci API.
Dapatkan Titik Akhir layanan

Anda dapat memanggil layanan melalui jaringan publik atau VPC. Untuk detailnya, lihat Dapatkan Titik Akhir Layanan.

Tugas pengenalan ucapan asinkron

Metode permintaan: POST

URL

POST {host}/v3/openapi/workspaces/{workspace_name}/audio-asr/{service_id}/async

host: Titik Akhir layanan. Anda dapat memanggil layanan API melalui jaringan publik atau dari VPC. Untuk informasi selengkapnya, lihat Dapatkan Titik Akhir Layanan.

Login ke Konsol AI Search Open Platform. Di pojok kiri atas, pilih ruang kerja target, misalnya, default (default space). Di panel navigasi sebelah kiri, klik API Keys. Di bagian access domain, Anda dapat menemukan public API domain dan private API domain.

workspace_name: Nama ruang kerja, contohnya default.
service_id: ID layanan bawaan, contohnya ops-audio-asr-001.

Parameter permintaan

Parameter header

Autentikasi Kunci API

Parameter	Tipe	Wajib	Deskripsi	Contoh
Content-Type	String	Ya	Jenis media dari badan permintaan.	application/json
Authorization	String	Ya	Kunci API	Bearer OS-d1**2a

Parameter Badan

Parameter	Tipe	Wajib	Deskripsi
input	Object(input)	Ya	File media yang akan diproses.
parameters	Object	Tidak	Parameter untuk layanan.
output	Object(output)	Ya	Konfigurasi output.

input

Parameter	Tipe	Wajib	Deskripsi
content	String	Tidak	Konten audio atau video yang dikodekan Base64. Format audio yang didukung: mp3, wav, aac, flac, ogg, m4a, alac, dan wma. Format video yang didukung: mp4, avi, mkv, mov, flv, dan webm. Catatan Parameter `input.content` dan `input.oss` saling eksklusif. Tentukan hanya salah satu. Gunakan data Base64: Masukkan data Base64 yang telah dikodekan ke parameter `content` dalam format `data:<TYPE>/<FORMAT>;base64,<BASE64_DATA>` , dengan: `<TYPE>/<FORMAT>` Untuk audio, seperti mp3, gunakan `audio/mp3`. Untuk video, seperti mov, gunakan `video/mov`. `<BASE64_DATA>`: Data audio atau video yang dikodekan BASE64. Contoh: Audio: data:audio/mp3;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj... Video: data:video/mov;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	Tidak	Jalur OSS file input. Contohnya, `oss://<bucket_name>/path/to/file.mp3`.
file_name	String	Tidak	Nama file audio atau video. Jika parameter ini tidak diatur, nama file diurai dari konten.

Output

Parameter

Tipe

Wajib

Deskripsi

type

String

Tidak

text: Mengembalikan hasil pengenalan ucapan sebagai teks biasa. Opsi ini hanya didukung untuk tugas sinkron.

oss: Menyimpan file output di bucket OSS. Ini adalah nilai default.

oss

String

Tidak

Jalur OSS untuk file output. Wajib jika type diatur ke oss.

Contoh: oss://<BUCKET_NAME>/result

Parameter respons

Parameter	Tipe	Deskripsi	Nilai contoh
result.task_id	String	Identifikasi unik untuk tugas pengenalan ucapan.	asr-xxxx-abc-123

Contoh curl

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/audio-asr/ops-audio-asr-001/async"
  --data '{
  "input":{
      "oss":"oss://<BUCKET_NAME>/xxx/xxx.mp3",
      "file_name":"xxx"
    },
    "output" :{
      "type":"oss",
      "oss":"oss://<BUCKET_NAME>/result"
    }
  }' \

Contoh respons

{
  "request_id": "3eb8de02091b59431601f3bff******",
  "latency": 37,
  "usage": {},
  "result": {
    "task_id": "asr-20250610164552-1108418170738252-******",
    "status": "PENDING"
  }
}

Status tugas pengenalan ucapan asinkron

Metode Permintaan: GET

URL

host: Titik Akhir layanan. Anda dapat memanggil layanan API melalui jaringan publik atau dari VPC. Untuk informasi selengkapnya, lihat Dapatkan Titik Akhir Layanan.
workspace_name: Nama ruang kerja, contohnya default.
service_id: ID layanan bawaan, contohnya ops-audio-asr-001.
task_id: ID unik untuk tugas pengenalan ucapan asinkron, yang dikembalikan dalam respons saat tugas dibuat.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi	Contoh
Content-Type	String	Ya	Jenis media permintaan.	application/json
Authorization	String	Ya	Kunci API untuk autentikasi.	Bearer OS-d1**2a

Parameter respons

Parameter	Tipe	Deskripsi	Contoh
request_id	String	ID permintaan.	3C09570D-12DB-46B4-BF0F-A100D79B****
latency	Float/Int	Latensi permintaan dalam milidetik.	3.0
result.task_id	String	ID tugas asinkron.	a7e4c0f6-874c-47e3-b05b-02278a96e****
result.status	String	Status tugas. Nilai yang valid adalah: `PENDING`: Tugas sedang menunggu pemrosesan. `SUCCESS`: Tugas berhasil diselesaikan. `FAIL`: Tugas gagal karena suatu error.	PENDING
result.error	String	Pesan error. Bidang ini memiliki nilai hanya ketika `result.status` bernilai `FAIL`.
result.data	List(AsrResult)	Hasil pengenalan ucapan. Bidang ini diisi hanya ketika status tugas asinkron adalah `SUCCESS`.
usage.duration	Float	Durasi file audio, dalam detik.

AsrResult

Parameter	Tipe	Deskripsi
text	String	Teks hasil transkripsi dari pengenalan ucapan.
start	Float	Timestamp awal teks dalam video, dalam detik.
end	Float	Timestamp akhir teks dalam video, dalam detik.

Contoh: Permintaan cURL

curl -X GET \
-H"Content-Type: application/json" \
-H "Authorization: Bearer <your_api_key>" \
"http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/audio-asr/ops-audio-asr-001/async/task-status?task_id=asr-20250618112151-1108418170738252-******"

Contoh respons

{
  "request_id": "1a1a4ca4b7a91dd630a40c54af******",
  "latency": 9,
  "usage": {
    "duration": 9
  },
  "result": {
    "task_id": "asr-20250618112151-1108418170738252-******",
    "status": "SUCCESS",
    "data": [
      {
        "text": "Rong Jielvdou began to speak, his voice as warm as the spring sun,",
        "start": 0.0,
        "end": 3.9
      },
      {
        "text": "full of life and warming the hearts of everyone who listened.",
        "start": 4.24,
        "end": 9.06
      }
    ]
  }
}

Membuat tugas pengenalan ucapan sinkron

Metode permintaan: POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/audio-asr/{service_id}/sync

host: Titik Akhir layanan. Anda dapat memanggil layanan API melalui jaringan publik atau VPC. Untuk informasi selengkapnya, lihat Dapatkan Titik Akhir Layanan.
workspace_name: Nama ruang kerja, seperti default.
service_id: ID layanan bawaan, seperti ops-audio-asr-001.

Parameter permintaan

Parameter header

Autentikasi Kunci API

Parameter	Tipe	Wajib	Deskripsi	Contoh
Content-Type	String	Ya	Menentukan jenis media dari badan permintaan.	application/json
Authorization	String	Ya	Kunci API untuk autentikasi, diawali dengan "Bearer ".	Bearer OS-d1**2a

Parameter body

Parameter	Tipe	Wajib	Deskripsi
input	Object(input)	Ya	File media yang akan diproses.
parameters	Object	Tidak	Parameter untuk layanan.
output	Object(output)	Ya	Konfigurasi output.

input

Parameter	Tipe	Wajib	Deskripsi
content	String	Tidak	Konten audio atau video yang dikodekan Base64. Format audio yang didukung: mp3, wav, aac, flac, ogg, m4a, alac, dan wma. Format video yang didukung: mp4, avi, mkv, mov, flv, dan webm. Catatan Parameter `input.content` dan `input.oss` saling eksklusif. Tentukan hanya salah satu. Gunakan data Base64: Masukkan data Base64 yang telah dikodekan ke parameter `content` dalam format `data:<TYPE>/<FORMAT>;base64,<BASE64_DATA>` , dengan: `<TYPE>/<FORMAT>` Untuk audio, seperti mp3, gunakan `audio/mp3`. Untuk video, seperti mov, gunakan `video/mov`. `<BASE64_DATA>`: Data audio atau video yang dikodekan BASE64. Contoh: Audio: data:audio/mp3;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj... Video: data:video/mov;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	Tidak	Jalur OSS file input. Contohnya, `oss://<bucket_name>/path/to/file.mp3`.
file_name	String	Tidak	Nama file audio atau video. Jika parameter ini tidak diatur, nama file diurai dari konten.

Output

Parameter

Tipe

Wajib

Deskripsi

type

String

Tidak

text: Mengembalikan hasil pengenalan ucapan sebagai teks biasa. Opsi ini hanya tersedia untuk panggilan sinkron.

oss: Menyimpan file video atau audio di OSS (default).

oss

String

Tidak

Jalur OSS untuk file output. Wajib ketika type bernilai oss.

contoh: oss://<BUCKET_NAME>/result

Parameter respons

Parameter	Tipe	Deskripsi	Nilai contoh
result.task_id	String	Identifikasi unik untuk tugas pengenalan ucapan.	asr-xxxx-abc-123

Permintaan Curl

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/audio-asr/ops-audio-asr-001/sync"
  --data '{
  "input":{
      "oss":"oss://<BUCKET_NAME>/xxx/xxx.mp3",
      "file_name":"xxx.mp3"
    },
    "output":{
      "type":"oss",
      "oss":"oss://<BUCKET_NAME>/result"
    }
  }' \

Contoh respons

{
  "request_id": "df96b5c444281e0e79561fe9f8******",
  "latency": 570,
  "usage": {
    "duration": 9
  },
  "result": {
    "task_id": "asr-20250618132401-1108418170738252-******",
    "status": "SUCCESS",
    "data": [
      {
        "text": "Rong Jielvdou began to speak, his voice as warm as the spring sun,",
        "start": 0.0,
        "end": 3.9
      },
      {
        "text": "full of life and warming the hearts of everyone who listened.",
        "start": 4.24,
        "end": 9.06
      }
    ]
  }
}

Kode status

Jika permintaan akses gagal, respons mencakup code dan message yang menjelaskan kesalahan tersebut.

{
    "request_id": "6F33AFB6-A35C-4DA7-AFD2-9EA16CCF****",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\""
}

Kode status HTTP	Kode error	Deskripsi
200	-	Permintaan berhasil meskipun tugas gagal. Periksa `result.status` untuk status aktual tugas.
404	BadRequest.TaskNotExist	Tugas yang ditentukan tidak ada.
400	InvalidParameter	Permintaan tidak valid.
500	InternalServerError	Terjadi error internal.

Untuk informasi lebih lanjut tentang kode status, lihat Deskripsi Kode Status.