# Bắt đầu nhanh

Chạy lần tạo sinh đầu tiên trong vài phút. Tất cả 1.496 mô hình đều nhận cùng một loại yêu cầu và trả về
cùng một đối tượng yêu cầu, cho hình ảnh, video và âm thanh: hãy học một lần tại đây.

> [!NOTE]
> URL cơ sở `https://api.doitong.com/v1`. Mọi lệnh gọi đều gửi `Authorization: Bearer <your key>`, và cùng một khóa hoạt động cho cả HTTP
> API và máy chủ MCP.

## 1. Nhận khóa API

Tạo khóa tại [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys) và lưu khóa trong một biến môi
trường: khóa chỉ được hiển thị một lần. Mỗi khóa có thể có ngân sách riêng, vì vậy bạn có thể cấp một khóa cho tác nhân
mà không gây rủi ro cho toàn bộ tài khoản. `GET /account` trả về số dư API của bạn.

```bash
export DOITONG_API_KEY="doitong_..."

curl "https://api.doitong.com/v1/account" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const res = await fetch("https://api.doitong.com/v1/account", {
  headers: { Authorization: `Bearer ${process.env.DOITONG_API_KEY}` },
});

console.log(await res.json());
```
```python
import os
import requests

r = requests.get(
    "https://api.doitong.com/v1/account",
    headers={"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"},
)
print(r.json())
```

Các lần chạy được thanh toán từ **số dư API** của tài khoản bằng tín dụng API: 1.000 tín dụng API = 1 $, và mỗi mô hình có đúng
mức giá của nhà cung cấp. Nạp tiền tại [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance).

## 2. Báo giá, rồi chạy

`POST /quote/{model_id}` nhận JSON đầu vào và trả về mức giá chính xác. Lệnh này không cần khóa và không mất phí.
Chạy cùng một đầu vào sẽ mất đúng số đó: báo giá chính là khoản phí. (Ngoại lệ là mô hình tính phí theo mức sử dụng: báo giá
là mức tối đa mà lần chạy có thể tốn, phần chưa sử dụng sẽ được hoàn tiền sau khi chạy.)

```bash
curl -X POST "https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video" \
  -H "Content-Type: application/json" \
  -d '{"image": "https://example.com/fox.jpg", "duration": 5, "generate_audio": true}'
```
```javascript
const res = await fetch("https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ image: "https://example.com/fox.jpg", duration: 5, generate_audio: true }),
});

const quote = await res.json();
console.log(quote.credits, quote.usd); // 840 "0.84"
```
```python
import requests

r = requests.post(
    "https://api.doitong.com/v1/quote/kling-video/v3/pro/image-to-video",
    json={"image": "https://example.com/fox.jpg", "duration": 5, "generate_audio": True},
)
print(r.json()["credits"], r.json()["usd"])  # 840 0.84
```

```json 200 OK · báo giá
{
  "object": "quote",
  "model": "kling-video/v3/pro/image-to-video",
  "credits": 840,
  "usd": "0.84",
  "unit": "second",
  "quantity": 5,
  "unit_credits": 168,
  "mode": "exact",
  "breakdown": "5 s × 168 API credits"
}
```

Sau đó gửi cùng nội dung đến `POST /run/{model_id}`. Thêm `?wait=20` để giữ kết nối tối đa 20 giây: mô hình nhanh sẽ trả về
kết quả hoàn tất trong một lượt khứ hồi. Gửi tiêu đề `Idempotency-Key` để một lần thử lại không bao giờ chạy (hoặc tính phí)
trùng lặp.

```bash
curl -X POST "https://api.doitong.com/v1/run/flux/schnell?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lighthouse-001" \
  -d '{"prompt": "A lighthouse on a rocky coast at dusk, warm light in the window"}'
```
```javascript
const res = await fetch("https://api.doitong.com/v1/run/flux/schnell?wait=20", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DOITONG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "lighthouse-001",
  },
  body: JSON.stringify({ prompt: "A lighthouse on a rocky coast at dusk, warm light in the window" }),
});

const request = await res.json();
console.log(request.status, request.outputs[0]?.url);
```
```python
import os
import requests

r = requests.post(
    "https://api.doitong.com/v1/run/flux/schnell",
    params={"wait": 20},
    headers={
        "Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}",
        "Idempotency-Key": "lighthouse-001",
    },
    json={"prompt": "A lighthouse on a rocky coast at dusk, warm light in the window"},
)
request = r.json()
print(request["status"], request["outputs"][0]["url"] if request["outputs"] else None)
```

Phản hồi là một đối tượng yêu cầu:

```json 200 OK · yêu cầu
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg", "width": 1024, "height": 768, "stored": true }
  ],
  "error": null
}
```

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

Nếu mô hình vẫn đang xử lý khi hết thời gian chờ, bạn nhận được `202 Accepted` cùng `id` và `status` hiện tại của yêu cầu.
Mọi yêu cầu đều đi qua cùng một vòng đời:

Vòng đời yêu cầu: `queued` → `running` → `succeeded` | `failed` | `canceled` (hoàn tất; các yêu cầu failed và canceled được hoàn tiền).

Đọc lại yêu cầu bằng id của nó. `?wait=20` cũng hoạt động ở đây, vì vậy chỉ cần một vòng lặp đơn giản:

```bash
curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```
```javascript
const headers = { Authorization: `Bearer ${process.env.DOITONG_API_KEY}` };
let request = await (await fetch("https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20", { headers })).json();

while (request.status === "queued" || request.status === "running") {
  const res = await fetch(`https://api.doitong.com/v1/requests/${request.id}?wait=20`, { headers });
  request = await res.json();
}

console.log(request.status, request.outputs[0]?.url);
```
```python
import os
import requests

headers = {"Authorization": f"Bearer {os.environ['DOITONG_API_KEY']}"}
request = {"id": "req_8k2m4q7x1z9c3v5b6n0p2r4t", "status": "queued"}

while request["status"] in ("queued", "running"):
    request = requests.get(
        f"https://api.doitong.com/v1/requests/{request['id']}",
        params={"wait": 20},
        headers=headers,
    ).json()

print(request["status"], request["outputs"][0]["url"] if request["outputs"] else None)
```

Khi `status` là `succeeded`, `outputs[].url` chứa các liên kết đến tệp trên hệ thống lưu trữ của chúng tôi. Nếu yêu cầu
`failed` hoặc `canceled`, tín dụng API sẽ được hoàn tiền tự động và `error` cho biết lý do. Hủy mọi yêu cầu vẫn đang ở trạng thái
`queued` hoặc `running`:

```bash
curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

Đối với các tác vụ video dài, bạn có thể bỏ qua việc thăm dò và thay vào đó truyền `webhook_url` (xem [Webhooks](https://doitong.com/developers/docs/webhooks)).

## 4. Tệp

Truyền bất kỳ URL công khai nào làm đầu vào, hoặc yêu cầu `POST /files` cung cấp URL tải lên, `PUT` tệp tại đó rồi sử dụng
`file_url` được trả về (xem [Files](https://doitong.com/developers/docs/files)). Một yêu cầu thành công liệt kê kết quả trong `outputs[]`,
bao gồm loại, loại nội dung và, khi có, kích thước cùng thời lượng.

```bash
curl -X POST "https://api.doitong.com/v1/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "fox.jpg", "content_type": "image/jpeg", "size": 482113}'
```

> [!TIP]
> **Giữ tệp vĩnh viễn hoặc miễn phí trong 7 ngày: bạn lựa chọn.** Tệp đầu ra được sao chép vào hệ thống
> lưu trữ của chúng tôi trước khi yêu cầu thành công. Theo mặc định, chúng được giữ lại cho đến khi bạn xóa (100 tín dụng API
> mỗi GB mỗi tháng); tắt "Lưu tệp vĩnh viễn" trong bảng điều khiển, hoặc truyền `?storage=temporary`, để giữ chúng trong
> 7 ngày miễn phí (xem [Files](https://doitong.com/developers/docs/files#storage)).

## Lỗi

Mọi mô hình đều gặp lỗi theo cùng một cách: một envelope có `type`, `code` chính xác, `param` gây lỗi và mọi vấn đề trong
`details`, để tác nhân có thể sửa yêu cầu mà không cần đọc phần văn bản mô tả. Yêu cầu không hợp lệ không bị tính phí.

```json 422 Unprocessable Entity
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

Mọi loại và mã lỗi được liệt kê trong [Errors](https://doitong.com/developers/docs/errors).

## Định giá

Giá được tính bằng USD và tín dụng API, đồng thời hiển thị trên trang của mỗi mô hình trước khi bạn chạy. Mỗi yêu cầu có
`cost` với `credits`, `usd`, `charged` và `refunded`. Một lần chạy bị tính phí khi được chấp nhận; các yêu cầu `failed` và
`canceled` được hoàn tiền tự động. Một số mô hình có giá được tính chính xác từ đầu vào, một số tính theo độ dài hoặc kích thước
của tệp bạn gửi, những mô hình khác tính *mức giá ước tính cho mỗi lần chạy*: trong mọi trường hợp, bạn trả đúng theo báo giá.
Một vài mô hình (mô hình ngôn ngữ và thị giác, giọng nói, công cụ tính theo thời gian xử lý) *tính phí theo mức sử dụng*: báo giá
là mức tối đa mà lần chạy có thể tốn, phần lần chạy không sử dụng sẽ được hoàn tiền tự động. Xem [Pricing](https://doitong.com/developers/docs/pricing).

## MCP và tác nhân AI

Kết nối mọi ứng dụng khách MCP với `https://api.doitong.com/v1/mcp` bằng cùng khóa Bearer. Tác nhân của bạn có thể tìm kiếm danh mục, báo giá và
chạy mô hình, đồng thời đọc mọi trang tài liệu dưới dạng Markdown.

```bash Claude Code
claude mcp add --transport http doitong-models https://api.doitong.com/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

## Bước tiếp theo

- Duyệt [tất cả mô hình](https://doitong.com/developers/models). Mỗi trang có trình tạo yêu cầu tự viết mã cho bạn.
- Tìm hiểu vòng đời yêu cầu: [Requests](https://doitong.com/developers/docs/requests).
- Sử dụng cùng tên tham số trên mọi mô hình: [Parameters](https://doitong.com/developers/docs/parameters).
- Đang làm việc với tác nhân lập trình AI? Cung cấp cho tác nhân [https://doitong.com/developers/llms.txt](https://doitong.com/developers/llms.txt) hoặc kết nối [máy chủ MCP](https://doitong.com/developers/docs/mcp).