NTS DEVELOPERS

API TTS / STT / Dịch

Tích hợp giọng đọc, nhận dạng giọng nói và dịch bằng web_api_key hiện có. Mã mẫu giữ nguyên cách gọi với cả domain mới và domain cũ.

Lấy web_api_key tại Tài khoản Tài liệu chat / ảnh / video nằm trong từng model →

Markdown Postman llms.txt

Tệp xuất chỉ chứa key mẫu.

TTS / STT / Dịch

TTS/STT/Dịch dùng web_api_key tại Tài khoản qua Authorization: Bearer. Hai loại key không thay thế nhau. Domain cũ tiếp tục hoạt động; chuyển sang domain mới chỉ thay hostname, giữ đường dẫn, key và nội dung. Gói, Credit ngày, cache và thu phí giữ cơ chế cũ: TTS theo ký tự từng dòng, STT làm tròn lên phút (tối thiểu 1), Dịch theo ký tự bản dịch. Phần đã xử lý có thể được thu phí khi tác vụ lỗi hoặc dừng. Hạn mức USD của API Model không áp dụng. POST tạo dự án cũ không có bảo đảm Idempotency-Key; khi mất phản hồi không tự gửi lại POST.

Địa chỉ APIhttps://api.ntsgenai.com/api/v1/public-api

web_api_key · /account

Lấy số dư credit

GEThttps://api.ntsgenai.com/api/v1/public-api/balance

Trả về số dư credit hiện tại (base_balance + daily_balance), credit miễn phí trong ngày, gói trả phí đang còn hạn và hạng VIP.

Response mẫu

{
  "success": true,
  "data": {
    "credit_balance": 105000,
    "base_balance": 100000,
    "daily_balance": 5000,
    "free_daily_credit": 5000,
    "free_chars_used": 0,
    "free_daily_char_limit": 1000000,
    "plans": [
      {
        "plan_id": "pro",
        "name": "Chuyên nghiệp",
        "daily_allowance": 100000,
        "expires_at": "2026-07-23 00:00:00"
      }
    ],
    "vip": {
      "tier": 1,
      "name": "Đồng"
    }
  }
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/balance \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Danh sách giọng

GEThttps://api.ntsgenai.com/api/v1/public-api/voices

Danh sách giọng đọc (phân trang + lọc). Mỗi giọng có `voice_id` là chuỗi opaque, dùng trực tiếp cho `voices[].voice_id` ở endpoint tạo TTS.

Tên	Kiểu	Bắt buộc	Mô tả
languagequery	string	—	Mã ngôn ngữ BCP-47 (vd `vi-VN`, `en-US`).
genderquery	string	—	`male` hoặc `female`.
tierquery	string	—	`free` / `standard` / `professional` / `professional_clone`.
searchquery	string	—	Tìm theo tên hoặc mô tả giọng.
sortquery	string	—	`popular` (mặc định) / `least` / `name`.
offsetquery	number	—	Bỏ qua N kết quả đầu.
limitquery	number	—	Số kết quả tối đa (mặc định 20).

Response mẫu

{
  "success": true,
  "data": [
    {
      "voice_id": "6748abc1234567890def0123",
      "name": "Hoài My",
      "language": "vi-VN",
      "gender": "female",
      "tier": "standard",
      "price_base": 1
    }
  ],
  "total": 100,
  "has_more": true
}

Mã ví dụ

curl --request GET \
  --url 'https://api.ntsgenai.com/api/v1/public-api/voices?language=vi-VN&sort=popular&offset=0&limit=20' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Tạo dự án TTS

POSThttps://api.ntsgenai.com/api/v1/public-api/tts

Tạo dự án text-to-speech rồi START luôn (giới hạn luồng y hệt giao diện web). Trả về `project_id` + `req_id` để theo dõi. Dự án sẽ hiện trên trang `/tts` của tài khoản.

Body (JSON)

Tên	Kiểu	Bắt buộc	Mô tả
namebody	string	✓	Tên dự án (hiển thị trên web).
source_typebody	string	—	`text` \| `srt` \| `vtt` \| `ass` (mặc định `text`).
has_timingbody	boolean	—	`true` nếu có dấu thời gian (SRT/VTT/ASS).
linesbody	array	✓	Mảng dòng: `[{ text, vocal_no }]` — `vocal_no` map sang `voices`.
voicesbody	array	✓	Mảng giọng: `[{ vocal_no, voice_id }]` — `voice_id` lấy từ `/voices`.

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "req_id": "fedcba987654321...",
    "status": "pending",
    "cost": 30
  }
}

Mã ví dụ

curl --request POST \
  --url https://api.ntsgenai.com/api/v1/public-api/tts \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My TTS project",
  "source_type": "text",
  "has_timing": false,
  "lines": [
    {
      "text": "Xin chào, đây là bản test của API.",
      "vocal_no": 1
    }
  ],
  "voices": [
    {
      "vocal_no": 1,
      "voice_id": "6748abc1234567890def0123"
    }
  ]
}'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Lấy kết quả

GEThttps://api.ntsgenai.com/api/v1/public-api/tts/{project_id}

Poll trạng thái dự án. Khi `status` = `done`, `audio_url` là URL file âm thanh (presigned 48 giờ); `srt_url` là file phụ đề (nếu có).

Tên	Kiểu	Bắt buộc	Mô tả
project_idpath	string	✓	ID dự án (trả về từ `POST /tts`).

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "name": "My TTS project",
    "status": "done",
    "progress": 100,
    "audio_url": "https://cdn.example.com/tts/user/abc.mp3?...",
    "srt_url": "",
    "queue_position": null,
    "created_at": "2026-06-23 10:00:00",
    "updated_at": "2026-06-23 10:02:30"
  }
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/tts/abc123def456789... \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Danh sách model STT

GEThttps://api.ntsgenai.com/api/v1/public-api/stt/models

Danh sách model nhận dạng giọng nói (Speech-to-Text). Mỗi model có `model_id` (dùng khi tạo dự án) và `credit_per_minute` (tỷ lệ trừ credit theo số phút audio).

Response mẫu

{
  "success": true,
  "data": [
    {
      "model_id": "whisper-standard",
      "name": "Whisper Standard",
      "credit_per_minute": 100,
      "description": "Nhận dạng giọng nói đa ngôn ngữ, có timestamp theo từ."
    }
  ]
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/stt/models \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Tạo dự án STT (nhận dạng)

POSThttps://api.ntsgenai.com/api/v1/public-api/stt/transcribe

Tạo dự án nhận dạng giọng nói rồi START luôn (giới hạn 2 luồng như web). Gửi dạng `multipart/form-data` hoặc `application/x-www-form-urlencoded`: hoặc `url_file` (link video/audio công khai) HOẶC tải lên `file` (multipart). Trả `project_id` + `req_id` để poll. Trừ credit theo PHÚT khi worker xử lý xong. Dự án hiện trên trang `/stt` của tài khoản.

Form · application/x-www-form-urlencoded

Tên	Kiểu	Bắt buộc	Mô tả
model_idbody	string	✓	ID model STT (lấy từ `/stt/models`).
url_filebody	string	—	Link video/audio công khai (YouTube/TikTok/link file trực tiếp). Bỏ trống nếu tải `file`.
filebody	string	—	File video/audio (multipart/form-data). Dùng khi KHÔNG có `url_file`.
languagebody	string	—	Mã ngôn ngữ nói (vd `vi`, `en`). Bỏ trống = tự động nhận diện.
namebody	string	—	Tên dự án (hiển thị trên /stt).

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "req_id": "fedcba987654321...",
    "status": "pending"
  }
}

Mã ví dụ

curl --request POST \
  --url https://api.ntsgenai.com/api/v1/public-api/stt/transcribe \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data model_id=whisper-standard \
  --data url_file=https://example.com/audio.mp3 \
  --data language= \
  --data 'name=My transcription'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Lấy kết quả STT

GEThttps://api.ntsgenai.com/api/v1/public-api/stt/{project_id}

Poll trạng thái dự án STT. Khi `status` = `done`, `transcript_url` là URL file JSON kết quả (chuẩn Whisper: `segments` + `words`, presigned 48 giờ). Tải URL đó để lấy nội dung phụ đề; xuất txt/srt/vtt/ass tự thực hiện phía bạn.

Tên	Kiểu	Bắt buộc	Mô tả
project_idpath	string	✓	ID dự án (trả về từ `POST /stt/transcribe`).

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "name": "My transcription",
    "status": "done",
    "progress": 100,
    "duration_seconds": 184.5,
    "segment_count": 42,
    "language": "vi",
    "transcript_url": "https://cdn.example.com/stt/user/abc.json?...",
    "queue_position": null,
    "created_at": "2026-06-26 10:00:00",
    "updated_at": "2026-06-26 10:03:10"
  }
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/stt/abc123def456789... \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Danh sách model dịch

GEThttps://api.ntsgenai.com/api/v1/public-api/translate/models

Danh sách model dịch phụ đề + danh sách ngôn ngữ đích hỗ trợ. Mỗi model có `model_id` (dùng khi tạo dự án) và `price_base` (tỷ lệ trừ credit / ký tự bản dịch). `languages` là tên ngôn ngữ đích hợp lệ cho `target_lang`.

Response mẫu

{
  "success": true,
  "data": {
    "models": [
      {
        "model_id": "context-10",
        "name": "Ngữ cảnh phim 10",
        "price_base": 10,
        "description": "Dịch theo ngữ cảnh, chất lượng phim."
      }
    ],
    "languages": [
      "Vietnamese",
      "English",
      "Japanese",
      "Korean"
    ]
  }
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/translate/models \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Tạo dự án dịch phụ đề

POSThttps://api.ntsgenai.com/api/v1/public-api/translate/subtitle

Gửi NỘI DUNG phụ đề định dạng SRT (`content`) rồi START luôn (giới hạn luồng + hàng đợi như web). Trả `project_id` + `req_id` để poll. Trừ credit theo số ký tự BẢN DỊCH khi xong. Dự án hiện trên trang `/translate` của tài khoản. `detect_mode`: `none` (không nhận dạng người nói) / `gender` (Nam–Nữ) / `multi` (nhiều người nói).

Body (JSON)

Tên	Kiểu	Bắt buộc	Mô tả
contentbody	string	✓	Nội dung phụ đề SRT (raw text — gồm số thứ tự, mốc thời gian, văn bản).
target_langbody	string	✓	Tên ngôn ngữ đích (PHẢI thuộc `languages` của `/translate/models`).
model_idbody	string	✓	ID model dịch (lấy từ `/translate/models`).
source_langbody	string	—	Tên ngôn ngữ nguồn. Bỏ trống = để engine tự nhận.
detect_modebody	string	—	`none` (mặc định) / `gender` / `multi` — nhận dạng người nói.
namebody	string	—	Tên dự án (hiển thị trên /translate).

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "req_id": "fedcba987654321...",
    "status": "pending"
  }
}

Mã ví dụ

curl --request POST \
  --url https://api.ntsgenai.com/api/v1/public-api/translate/subtitle \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "content": "1\n00:00:01,000 --> 00:00:02,500\nHello world\n\n2\n00:00:03,000 --> 00:00:04,000\nHow are you?",
  "target_lang": "Vietnamese",
  "model_id": "context-10",
  "source_lang": "English",
  "detect_mode": "none",
  "name": "My translation"
}'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Lấy kết quả dịch

GEThttps://api.ntsgenai.com/api/v1/public-api/translate/{project_id}

Poll trạng thái dự án dịch. Mảng `lines` cập nhật dần: mỗi dòng có `text` (gốc), `translate_text` (bản dịch), `vocal` (số người nói khi `detect_mode` ≠ `none`). Khi `status` = `done` là dịch xong; bạn tự dựng SRT/VTT/ASS/JSON từ `lines`.

Tên	Kiểu	Bắt buộc	Mô tả
project_idpath	string	✓	ID dự án (trả về từ `POST /translate/subtitle`).

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "name": "My translation",
    "status": "done",
    "progress": 100,
    "source_lang": "English",
    "target_lang": "Vietnamese",
    "detect_mode": "none",
    "segment_count": 2,
    "translated_lines": 2,
    "lines": [
      {
        "line_no": 1,
        "start_time": "00:00:01,000",
        "end_time": "00:00:02,500",
        "text": "Hello world",
        "translate_text": "Xin chào thế giới",
        "vocal": 0
      }
    ],
    "queue_position": null,
    "created_at": "2026-06-29 10:00:00",
    "updated_at": "2026-06-29 10:01:20"
  }
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/translate/abc123def456789... \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

Tạo → Tra cứu → Tải kết quả

Mẫu endpoint có 10 ngôn ngữ. Ví dụ luồng đầy đủ bên dưới chạy bằng Python (pip install requests) hoặc Node.js 18+. Thay mã model/giọng bằng danh mục được cấp quyền. Chỉ POST tạo một lần, lưu mã công việc, tra cứu có giới hạn thời gian rồi tải kết quả; không gửi API key đến máy chủ chứa file. Hết thời gian chờ không có nghĩa job đã bị hủy. MCP chưa cung cấp trong phiên bản này.

# Python 3: pip install requests
import json, os, time, uuid
from pathlib import Path
from urllib.parse import quote, urlparse
import requests

BASE = "https://api.ntsgenai.com/api/v1/public-api"
KEY = os.environ["NTS_WEB_API_KEY"]
headers = {"Authorization": "Bearer " + KEY}
# Legacy creation has no idempotency guarantee. Never automatically retry POST.
payload = json.loads("{\"name\":\"My TTS project\",\"source_type\":\"text\",\"has_timing\":false,\"lines\":[{\"text\":\"Xin chào, đây là bản test của API.\",\"vocal_no\":1}],\"voices\":[{\"vocal_no\":1,\"voice_id\":\"6748abc1234567890def0123\"}]}")
# Replace sample model / voice IDs using the catalog first.
created = requests.post(BASE + "/tts", headers=headers,
    json=payload, timeout=330, allow_redirects=False)
created.raise_for_status()
if created.status_code >= 300: raise RuntimeError("Unexpected redirect")
document = created.json()
if document.get("success") is False: raise RuntimeError(document)
job_id = document["data"]["project_id"]
Path("nts-job-id.txt").write_text(job_id, encoding="utf-8")
print("Saved job:", job_id)
deadline = time.monotonic() + 1800
while True:
    response = requests.get(BASE + "/tts/__JOB_ID__".replace("__JOB_ID__", quote(job_id, safe="")),
        headers={"Authorization": "Bearer " + KEY}, timeout=60, allow_redirects=False)
    response.raise_for_status()
    if response.status_code >= 300: raise RuntimeError("Unexpected redirect")
    document = response.json()
    if document.get("success") is False: raise RuntimeError(document)
    job = document["data"]
    print(job["status"])
    if job["status"] in ("completed", "done", "succeeded"): break
    if job["status"] in ("failed", "error", "cancelled", "stopped", "needs_review"):
        raise RuntimeError(job)  # Reconcile this job; do not submit a replacement automatically.
    if time.monotonic() >= deadline: raise TimeoutError("Keep job ID; poll again later")
    time.sleep(3)
url = job.get("audio_url")
if not url: raise RuntimeError("No download URL; retain job ID and check expiry")
if urlparse(url).scheme != "https": raise RuntimeError("Expected HTTPS result URL")
# No Authorization header on the signed storage URL.
with requests.get(url, stream=True, timeout=120, allow_redirects=False) as download:
    download.raise_for_status()
    if download.status_code >= 300: raise RuntimeError("Unexpected storage redirect")
    with open("audio.wav", "wb") as output:
        for chunk in download.iter_content(1024 * 1024): output.write(chunk)
print("Saved", "audio.wav")

NTS DEVELOPERS

API TTS / STT / Dịch

Tích hợp giọng đọc, nhận dạng giọng nói và dịch bằng web_api_key hiện có. Mã mẫu giữ nguyên cách gọi với cả domain mới và domain cũ.

Lấy web_api_key tại Tài khoản Tài liệu chat / ảnh / video nằm trong từng model →

Markdown Postman llms.txt

Tệp xuất chỉ chứa key mẫu.

TTS / STT / Dịch

Địa chỉ APIhttps://api.ntsgenai.com/api/v1/public-api

web_api_key · /account

Lấy số dư credit

GEThttps://api.ntsgenai.com/api/v1/public-api/balance

Trả về số dư credit hiện tại (base_balance + daily_balance), credit miễn phí trong ngày, gói trả phí đang còn hạn và hạng VIP.

Response mẫu

{
  "success": true,
  "data": {
    "credit_balance": 105000,
    "base_balance": 100000,
    "daily_balance": 5000,
    "free_daily_credit": 5000,
    "free_chars_used": 0,
    "free_daily_char_limit": 1000000,
    "plans": [
      {
        "plan_id": "pro",
        "name": "Chuyên nghiệp",
        "daily_allowance": 100000,
        "expires_at": "2026-07-23 00:00:00"
      }
    ],
    "vip": {
      "tier": 1,
      "name": "Đồng"
    }
  }
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/balance \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Danh sách giọng

GEThttps://api.ntsgenai.com/api/v1/public-api/voices

Danh sách giọng đọc (phân trang + lọc). Mỗi giọng có `voice_id` là chuỗi opaque, dùng trực tiếp cho `voices[].voice_id` ở endpoint tạo TTS.

Tên	Kiểu	Bắt buộc	Mô tả
languagequery	string	—	Mã ngôn ngữ BCP-47 (vd `vi-VN`, `en-US`).
genderquery	string	—	`male` hoặc `female`.
tierquery	string	—	`free` / `standard` / `professional` / `professional_clone`.
searchquery	string	—	Tìm theo tên hoặc mô tả giọng.
sortquery	string	—	`popular` (mặc định) / `least` / `name`.
offsetquery	number	—	Bỏ qua N kết quả đầu.
limitquery	number	—	Số kết quả tối đa (mặc định 20).

Response mẫu

{
  "success": true,
  "data": [
    {
      "voice_id": "6748abc1234567890def0123",
      "name": "Hoài My",
      "language": "vi-VN",
      "gender": "female",
      "tier": "standard",
      "price_base": 1
    }
  ],
  "total": 100,
  "has_more": true
}

Mã ví dụ

curl --request GET \
  --url 'https://api.ntsgenai.com/api/v1/public-api/voices?language=vi-VN&sort=popular&offset=0&limit=20' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Tạo dự án TTS

POSThttps://api.ntsgenai.com/api/v1/public-api/tts

Body (JSON)

Tên	Kiểu	Bắt buộc	Mô tả
namebody	string	✓	Tên dự án (hiển thị trên web).
source_typebody	string	—	`text` \| `srt` \| `vtt` \| `ass` (mặc định `text`).
has_timingbody	boolean	—	`true` nếu có dấu thời gian (SRT/VTT/ASS).
linesbody	array	✓	Mảng dòng: `[{ text, vocal_no }]` — `vocal_no` map sang `voices`.
voicesbody	array	✓	Mảng giọng: `[{ vocal_no, voice_id }]` — `voice_id` lấy từ `/voices`.

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "req_id": "fedcba987654321...",
    "status": "pending",
    "cost": 30
  }
}

Mã ví dụ

curl --request POST \
  --url https://api.ntsgenai.com/api/v1/public-api/tts \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My TTS project",
  "source_type": "text",
  "has_timing": false,
  "lines": [
    {
      "text": "Xin chào, đây là bản test của API.",
      "vocal_no": 1
    }
  ],
  "voices": [
    {
      "vocal_no": 1,
      "voice_id": "6748abc1234567890def0123"
    }
  ]
}'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Lấy kết quả

GEThttps://api.ntsgenai.com/api/v1/public-api/tts/{project_id}

Poll trạng thái dự án. Khi `status` = `done`, `audio_url` là URL file âm thanh (presigned 48 giờ); `srt_url` là file phụ đề (nếu có).

Tên	Kiểu	Bắt buộc	Mô tả
project_idpath	string	✓	ID dự án (trả về từ `POST /tts`).

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "name": "My TTS project",
    "status": "done",
    "progress": 100,
    "audio_url": "https://cdn.example.com/tts/user/abc.mp3?...",
    "srt_url": "",
    "queue_position": null,
    "created_at": "2026-06-23 10:00:00",
    "updated_at": "2026-06-23 10:02:30"
  }
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/tts/abc123def456789... \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Danh sách model STT

GEThttps://api.ntsgenai.com/api/v1/public-api/stt/models

Danh sách model nhận dạng giọng nói (Speech-to-Text). Mỗi model có `model_id` (dùng khi tạo dự án) và `credit_per_minute` (tỷ lệ trừ credit theo số phút audio).

Response mẫu

{
  "success": true,
  "data": [
    {
      "model_id": "whisper-standard",
      "name": "Whisper Standard",
      "credit_per_minute": 100,
      "description": "Nhận dạng giọng nói đa ngôn ngữ, có timestamp theo từ."
    }
  ]
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/stt/models \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Tạo dự án STT (nhận dạng)

POSThttps://api.ntsgenai.com/api/v1/public-api/stt/transcribe

Form · application/x-www-form-urlencoded

Tên	Kiểu	Bắt buộc	Mô tả
model_idbody	string	✓	ID model STT (lấy từ `/stt/models`).
url_filebody	string	—	Link video/audio công khai (YouTube/TikTok/link file trực tiếp). Bỏ trống nếu tải `file`.
filebody	string	—	File video/audio (multipart/form-data). Dùng khi KHÔNG có `url_file`.
languagebody	string	—	Mã ngôn ngữ nói (vd `vi`, `en`). Bỏ trống = tự động nhận diện.
namebody	string	—	Tên dự án (hiển thị trên /stt).

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "req_id": "fedcba987654321...",
    "status": "pending"
  }
}

Mã ví dụ

curl --request POST \
  --url https://api.ntsgenai.com/api/v1/public-api/stt/transcribe \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data model_id=whisper-standard \
  --data url_file=https://example.com/audio.mp3 \
  --data language= \
  --data 'name=My transcription'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Lấy kết quả STT

GEThttps://api.ntsgenai.com/api/v1/public-api/stt/{project_id}

Tên	Kiểu	Bắt buộc	Mô tả
project_idpath	string	✓	ID dự án (trả về từ `POST /stt/transcribe`).

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "name": "My transcription",
    "status": "done",
    "progress": 100,
    "duration_seconds": 184.5,
    "segment_count": 42,
    "language": "vi",
    "transcript_url": "https://cdn.example.com/stt/user/abc.json?...",
    "queue_position": null,
    "created_at": "2026-06-26 10:00:00",
    "updated_at": "2026-06-26 10:03:10"
  }
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/stt/abc123def456789... \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Danh sách model dịch

GEThttps://api.ntsgenai.com/api/v1/public-api/translate/models

Response mẫu

{
  "success": true,
  "data": {
    "models": [
      {
        "model_id": "context-10",
        "name": "Ngữ cảnh phim 10",
        "price_base": 10,
        "description": "Dịch theo ngữ cảnh, chất lượng phim."
      }
    ],
    "languages": [
      "Vietnamese",
      "English",
      "Japanese",
      "Korean"
    ]
  }
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/translate/models \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Tạo dự án dịch phụ đề

POSThttps://api.ntsgenai.com/api/v1/public-api/translate/subtitle

Body (JSON)

Tên	Kiểu	Bắt buộc	Mô tả
contentbody	string	✓	Nội dung phụ đề SRT (raw text — gồm số thứ tự, mốc thời gian, văn bản).
target_langbody	string	✓	Tên ngôn ngữ đích (PHẢI thuộc `languages` của `/translate/models`).
model_idbody	string	✓	ID model dịch (lấy từ `/translate/models`).
source_langbody	string	—	Tên ngôn ngữ nguồn. Bỏ trống = để engine tự nhận.
detect_modebody	string	—	`none` (mặc định) / `gender` / `multi` — nhận dạng người nói.
namebody	string	—	Tên dự án (hiển thị trên /translate).

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "req_id": "fedcba987654321...",
    "status": "pending"
  }
}

Mã ví dụ

curl --request POST \
  --url https://api.ntsgenai.com/api/v1/public-api/translate/subtitle \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "content": "1\n00:00:01,000 --> 00:00:02,500\nHello world\n\n2\n00:00:03,000 --> 00:00:04,000\nHow are you?",
  "target_lang": "Vietnamese",
  "model_id": "context-10",
  "source_lang": "English",
  "detect_mode": "none",
  "name": "My translation"
}'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

web_api_key · /account

Lấy kết quả dịch

GEThttps://api.ntsgenai.com/api/v1/public-api/translate/{project_id}

Tên	Kiểu	Bắt buộc	Mô tả
project_idpath	string	✓	ID dự án (trả về từ `POST /translate/subtitle`).

Response mẫu

{
  "success": true,
  "data": {
    "project_id": "abc123def456789...",
    "name": "My translation",
    "status": "done",
    "progress": 100,
    "source_lang": "English",
    "target_lang": "Vietnamese",
    "detect_mode": "none",
    "segment_count": 2,
    "translated_lines": 2,
    "lines": [
      {
        "line_no": 1,
        "start_time": "00:00:01,000",
        "end_time": "00:00:02,500",
        "text": "Hello world",
        "translate_text": "Xin chào thế giới",
        "vocal": 0
      }
    ],
    "queue_position": null,
    "created_at": "2026-06-29 10:00:00",
    "updated_at": "2026-06-29 10:01:20"
  }
}

Mã ví dụ

curl --request GET \
  --url https://api.ntsgenai.com/api/v1/public-api/translate/abc123def456789... \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Snippet hiển thị payload mẫu — chỉnh giá trị trong code sau khi sao chép. Bạn có thể dùng panel "Thử ngay" bên dưới để gửi request với dữ liệu tùy ý.

Thử ngay · web_api_key · /account

Tạo → Tra cứu → Tải kết quả

# Python 3: pip install requests
import json, os, time, uuid
from pathlib import Path
from urllib.parse import quote, urlparse
import requests

BASE = "https://api.ntsgenai.com/api/v1/public-api"
KEY = os.environ["NTS_WEB_API_KEY"]
headers = {"Authorization": "Bearer " + KEY}
# Legacy creation has no idempotency guarantee. Never automatically retry POST.
payload = json.loads("{\"name\":\"My TTS project\",\"source_type\":\"text\",\"has_timing\":false,\"lines\":[{\"text\":\"Xin chào, đây là bản test của API.\",\"vocal_no\":1}],\"voices\":[{\"vocal_no\":1,\"voice_id\":\"6748abc1234567890def0123\"}]}")
# Replace sample model / voice IDs using the catalog first.
created = requests.post(BASE + "/tts", headers=headers,
    json=payload, timeout=330, allow_redirects=False)
created.raise_for_status()
if created.status_code >= 300: raise RuntimeError("Unexpected redirect")
document = created.json()
if document.get("success") is False: raise RuntimeError(document)
job_id = document["data"]["project_id"]
Path("nts-job-id.txt").write_text(job_id, encoding="utf-8")
print("Saved job:", job_id)
deadline = time.monotonic() + 1800
while True:
    response = requests.get(BASE + "/tts/__JOB_ID__".replace("__JOB_ID__", quote(job_id, safe="")),
        headers={"Authorization": "Bearer " + KEY}, timeout=60, allow_redirects=False)
    response.raise_for_status()
    if response.status_code >= 300: raise RuntimeError("Unexpected redirect")
    document = response.json()
    if document.get("success") is False: raise RuntimeError(document)
    job = document["data"]
    print(job["status"])
    if job["status"] in ("completed", "done", "succeeded"): break
    if job["status"] in ("failed", "error", "cancelled", "stopped", "needs_review"):
        raise RuntimeError(job)  # Reconcile this job; do not submit a replacement automatically.
    if time.monotonic() >= deadline: raise TimeoutError("Keep job ID; poll again later")
    time.sleep(3)
url = job.get("audio_url")
if not url: raise RuntimeError("No download URL; retain job ID and check expiry")
if urlparse(url).scheme != "https": raise RuntimeError("Expected HTTPS result URL")
# No Authorization header on the signed storage URL.
with requests.get(url, stream=True, timeout=120, allow_redirects=False) as download:
    download.raise_for_status()
    if download.status_code >= 300: raise RuntimeError("Unexpected storage redirect")
    with open("audio.wav", "wb") as output:
        for chunk in download.iter_content(1024 * 1024): output.write(chunk)
print("Saved", "audio.wav")