# Bắt đầu nhanh

Ba bước để có file audio đầu tiên - tạo khóa, nạp credit, chạy code.

## 1. Tạo khóa API

Đăng nhập, vào **Khóa API** trong dashboard và bấm **Tạo khóa**. Khóa có dạng `sk_live_...` và **chỉ hiện một lần** lúc tạo: hãy lưu ngay vào trình quản lý bí mật. Sau đó dashboard chỉ còn hiện phần đầu (prefix) của khóa.

Đặt khóa vào biến môi trường để các ví dụ dưới đây dùng được:

```bash
export SOTA_API_KEY="sk_live_..."
```

Không bao giờ đưa khóa vào code chạy trên trình duyệt. Xem [Xác thực](/docs-md/authentication.md).

## 2. Nạp credit

Vào **Credit** trong dashboard, chọn gói và chuyển khoản theo mã VietQR. Credit được cộng khi giao dịch về, không hết hạn. Kiểm tra số dư bằng API:

```bash
curl https://api.example.com/v1/credits \
  -H "Authorization: Bearer $SOTA_API_KEY"
```

```json
{"object":"credit_balance","available":482300,"unit":"character"}
```

## 3. Chạy code

Dùng SDK của OpenAI, chỉ đổi `base_url` sang gateway Sota Voice và model sang `sota-voice-v1`.

```bash tab="curl"
curl https://api.example.com/v1/audio/speech \
  -H "Authorization: Bearer $SOTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sota-voice-v1","voice":"default","input":"Xin chào, đây là Sota Voice.","response_format":"mp3"}' \
  --output speech.mp3
```

```python tab="Python"
import os
from openai import OpenAI  # pip install openai

client = OpenAI(
    base_url="https://api.example.com/v1",
    api_key=os.environ["SOTA_API_KEY"],
)

with client.audio.speech.with_streaming_response.create(
    model="sota-voice-v1",
    voice="default",
    input="Xin chào, đây là Sota Voice.",
    response_format="mp3",
) as response:
    response.stream_to_file("speech.mp3")
```

```js tab="JavaScript"
import fs from 'node:fs';
import OpenAI from 'openai'; // npm i openai

const client = new OpenAI({
  baseURL: 'https://api.example.com/v1',
  apiKey: process.env.SOTA_API_KEY,
});

const audio = await client.audio.speech.create({
  model: 'sota-voice-v1',
  voice: 'default',
  input: 'Xin chào, đây là Sota Voice.',
  response_format: 'mp3',
});
fs.writeFileSync('speech.mp3', Buffer.from(await audio.arrayBuffer()));
```

Mở `speech.mp3` để nghe. Bạn bị trừ đúng số ký tự của `input` (ở đây là 28).

Danh sách giọng có sẵn và giọng bạn đã nhân bản: `GET /v1/audio/voices`. Tham số `voice` nhận tên giọng có sẵn (ví dụ `default`, `zh_1`, `en_a`) hoặc `name` của giọng bạn đã nhân bản.

## Tiếp theo

- [Voice agent qua WebSocket](/docs-md/realtime-websocket.md): đọc ngay khi LLM đang sinh chữ.
- [Job bất đồng bộ](/docs-md/async-jobs.md): đọc văn bản dài, nhận webhook khi xong.
- [Mã lỗi](/docs-md/errors.md) và [Giới hạn tốc độ](/docs-md/rate-limits.md).
- Thử API trong Postman: import [`sota-voice.postman_collection.json`](/sota-voice.postman_collection.json), rồi đặt biến `baseUrl` và `apiKey` của collection.

