# Bắt đầu nhanh

Source: https://docs.vieneu.io/vi/docs/cloud-api/quickstart

Ba bước, và bước thứ ba trả về audio. Không bước nào cần đến SDK.

## 1. Lấy API key {#1-get-an-api-key}

Key nằm ở **[trang Developer](https://www.vieneu.io/#/developer?create=test)** trong web
app VieNeu. Tạo một key, sao chép ngay lần đầu — chuỗi gốc chỉ hiện đúng lúc tạo và
không bao giờ hiện lại — rồi đặt nó vào biến môi trường:

```bash
export VIENEU_API_KEY="vn_sk_..."
```

Key chỉ được cấp khi tài khoản đang có một **token grant còn hiệu lực**, nên tài
khoản mới tinh phải kích hoạt một grant trước; trang Developer có bản dùng thử miễn
phí 7 ngày làm đúng việc đó, mỗi tài khoản một lần. Không có grant, lệnh tạo key trả
về `403` kèm `No active API token grant found.`

Key bắt đầu bằng `vn_sk_` là key thật. Key `vn_test_` hoạt động y hệt — cùng cách
tính phí, cùng giới hạn, cùng endpoint — chỉ khác là mỗi request bị giới hạn 100 từ,
nên bạn có thể yên tâm dán chúng vào repo mẫu.

## 2. Chọn giọng {#2-pick-a-voice}

Danh mục giọng là công khai — lời gọi này không cần key:

```bash
curl -s "https://api.vieneu.io/api/v1/voices?engine=v4" | head -c 400
```

```json
{"voices":[{"id":"Ngọc Lan","description":"Giọng nữ, giọng trầm dịu dàng",
  "name":"Ngọc Lan","gender":"female","region":"south","engine":"v4",
  "kind":"catalog"}, …]}
```

Trường `id` là thứ bạn gửi đi. **Luôn lọc theo engine.** Mỗi giọng chỉ thuộc về một
engine, hai danh mục chỉ thay cho nhau được một phần, và gửi id của engine kia sẽ
nhận `400` chứ không được thay bằng giọng khác — xem
[voice id khác nhau theo engine](./overview.md#voice-ids-differ-by-engine).

## 3. Tổng hợp giọng nói {#3-synthesize}

`POST /v1/audio/speech` trả thẳng các byte audio ngay trong response — không job,
không polling. Đây chính là dạng endpoint của OpenAI, nên client OpenAI dùng được
ngay mà không phải sửa gì; xem [endpoint tương thích OpenAI](./openai-compatible.md).

### curl {#curl}

```bash
curl https://api.vieneu.io/api/v1/audio/speech \
  -H "Authorization: Bearer $VIENEU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": "Xin chào, đây là VieNeu.", "voice": "Ngọc Lan" }' \
  --output speech.mp3
```

### Python {#python}

```python
# pip install requests
import os
import requests

resp = requests.post(
    "https://api.vieneu.io/api/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['VIENEU_API_KEY']}"},
    json={"input": "Xin chào, đây là VieNeu.", "voice": "Ngọc Lan"},
    timeout=120,
)
resp.raise_for_status()
with open("speech.mp3", "wb") as f:
    f.write(resp.content)
print("wrote speech.mp3", len(resp.content), "bytes")
```

### JavaScript {#javascript}

```js
// Node 18+ — no dependencies.
import { writeFile } from 'node:fs/promises';

const resp = await fetch('https://api.vieneu.io/api/v1/audio/speech', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIENEU_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ input: 'Xin chào, đây là VieNeu.', voice: 'Ngọc Lan' }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);

await writeFile('speech.mp3', Buffer.from(await resp.arrayBuffer()));
console.log('wrote speech.mp3');
```

Vậy là bạn đã có một tệp mp3. Muốn định dạng khác thì đổi `response_format` — `wav`,
`opus`, `pcm` và `ulaw` 8 kHz đều dùng được, chi tiết từng trường nằm trong
[tài liệu API](/api-reference), ở mục `createSpeech`.

## Đi tiếp từ đây {#where-to-go-next}

- **Văn bản dài** — `/v1/audio/speech` giữ kết nối mở suốt quá trình tổng hợp. Dài
  hơn vài đoạn văn thì hãy gửi một job thay vì gọi trực tiếp: xem
  [hai cách tổng hợp](./overview.md#the-two-ways-to-synthesize).
- **Phát audio trước khi tổng hợp xong văn bản** — [Streaming](./streaming.md).
- **Khi request lỗi** — [Lỗi](./errors.md) liệt kê mọi `code` máy đọc được và cách
  xử lý từng loại.
- **Mọi thứ còn lại** — [tài liệu API](/api-reference) được sinh ra từ chính định
  nghĩa route của server và bao quát mọi trường của mọi endpoint.