# Job bất đồng bộ

Đọc văn bản dài (đến 100.000 ký tự), theo dõi trạng thái và tải file audio.

Với văn bản dài (sách, bài báo, kịch bản), tạo một job: API trả về ngay với `status: "queued"`, việc sinh audio chạy nền. Khi xong, bạn nhận [webhook](/docs-md/webhooks.md) hoặc hỏi lại trạng thái, rồi tải file.

## Tạo job

```bash tab="curl"
curl https://api.example.com/v1/audio/speech/jobs \
  -H "Authorization: Bearer $SOTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d3f6c1e-4a52-4c1b-9a86-2f0e5b8d1c34" \
  -d '{"model":"sota-voice-v1","voice":"default","input":"Chương một. Ngày xửa ngày xưa...","response_format":"mp3","webhook_url":"https://example.com/hooks/sota"}'
```

```python tab="Python"
import os
import uuid
import httpx

job = httpx.post(
    "https://api.example.com/v1/audio/speech/jobs",
    headers={
        "Authorization": f"Bearer {os.environ['SOTA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # lưu lại để retry an toàn
    },
    json={
        "model": "sota-voice-v1",
        "voice": "default",
        "input": open("chapter-1.txt", encoding="utf-8").read(),
        "response_format": "mp3",
        "webhook_url": "https://example.com/hooks/sota",
    },
).raise_for_status().json()
print(job["id"], job["status"])  # job_..., queued
```

```json
{
  "id": "job_01jd8x3k9q4m7n2p5r6s8t0v1w",
  "object": "speech.job",
  "status": "queued",
  "model": "sota-voice-v1",
  "voice": "default",
  "response_format": "mp3",
  "characters": 1840,
  "webhook_url": "https://example.com/hooks/sota",
  "created_at": 1763366400,
  "started_at": null,
  "completed_at": null,
  "expires_at": null,
  "error": null
}
```

- `input` tối đa 100.000 ký tự (code point NFC). Các field khác như `POST /v1/audio/speech` (`voice`, `response_format`, `literal_punctuation`; không có `split_granularity`, tùy chọn chỉ dành cho WebSocket); tùy chọn stream bị bỏ qua. Tổng các field ngoài `input` phải dưới 16 KiB.
- `webhook_url` phải là `https` và không trỏ tới địa chỉ IP nội bộ, nếu không: `422 invalid_webhook_url`.

## Idempotency

Gửi header `Idempotency-Key` (1-255 ký tự, ví dụ một UUID) để retry không tạo và tính phí job thứ hai:

- Cùng key, cùng body: trả lại job ban đầu, kèm header `Idempotent-Replayed: true`.
- Cùng key, body khác: `409 idempotency_key_reused`.
- Key không dài 1-255 ký tự: `422 idempotency_key_invalid`.

## Vòng đời và tính phí

```text
queued ──▶ in_progress ──▶ completed   (trừ credit, lưu audio 7 ngày)
   │                  └──▶ failed      (trả lại credit giữ trước, có error)
   └──▶ cancelled                      (trả lại credit giữ trước)
```

- Khi tạo, credit bằng số ký tự của `input` được **giữ trước**. Không đủ: `402 insufficient_credit`.
- `completed`: bị tính phí; audio lưu **7 ngày** (`expires_at`).
- `failed` hoặc `cancelled`: phần giữ trước được trả lại. `error` có `code` (cùng bảng [mã lỗi](/docs-md/errors.md)) và `message`.
- Job bất đồng bộ không tính vào giới hạn request realtime đồng thời.

## Theo dõi trạng thái

Ưu tiên [webhook](/docs-md/webhooks.md). Nếu cần hỏi lại, gọi `GET /v1/audio/speech/jobs/{id}` với khoảng cách vài giây:

```bash
curl https://api.example.com/v1/audio/speech/jobs/job_01jd8x3k9q4m7n2p5r6s8t0v1w \
  -H "Authorization: Bearer $SOTA_API_KEY"
```

Liệt kê job: `GET /v1/audio/speech/jobs` (mới nhất trước), phân trang bằng `limit` (1-100, mặc định 20), `after`, `before`, `order`.

## Hủy job

`POST /v1/audio/speech/jobs/{id}/cancel` hủy job còn `queued` và trả lại credit. Job đang chạy hoặc đã xong: `409 job_not_cancellable`.

## Tải audio

`GET /v1/audio/speech/jobs/{id}/content` trả `302` tới một URL tải có chữ ký, hiệu lực 15 phút. Khi theo redirect, **đừng** gửi header `Authorization` tới máy chủ lưu trữ (`curl -L` và hầu hết HTTP client tự bỏ header này khi đổi host).

```bash
curl -L https://api.example.com/v1/audio/speech/jobs/job_01jd8x3k9q4m7n2p5r6s8t0v1w/content \
  -H "Authorization: Bearer $SOTA_API_KEY" \
  --output chapter-1.mp3
```

- Job chưa `completed`: `409 job_not_ready`.
- Sau 7 ngày audio bị xóa: `410 job_expired`.

