---
title: "API /api/v1 cho pipeline"
url: https://phatdev.net/docs/media-studio/api-v1
lang: vi
updated: 2026-10-20
alternate:
  en: https://phatdev.net/en/docs/media-studio/api-v1
markdown: https://phatdev.net/docs/media-studio/api-v1.md
---

# API /api/v1 cho pipeline

Thuộc bộ tài liệu: [Media Studio](https://phatdev.net/docs/media-studio.md)

> Xác thực bằng key, job nền, idempotency, header x-engine, danh sách endpoint và mã lỗi.

Mọi tính năng của Media Studio đều gọi được qua REST API - đây là cách pipeline viết bài tự lấy ảnh, banner, biểu đồ và video.

## Xác thực

- Tạo key trong **Cài đặt → API keys** (mỗi dịch vụ một key). Gửi header `x-api-token: <key>`.
- **Fail-closed**: chưa tạo key nào thì API **bị khoá**, không phải mở.
- Không cần key: `GET /api/v1/info`, `/api/v1/openapi.json`, `/api/v1/docs`, `/api/v1/health`.

```bash
curl https://media.phatdev.net/api/v1/info          # mọi tham số + endpoint
curl https://media.phatdev.net/api/v1/openapi.json  # đặc tả OpenAPI 3.0
curl https://media.phatdev.net/api/v1/health        # phiên bản, engine sẵn sàng, hạn mức
```

## Job nền & chống gen trùng

Các việc lâu (review-pack 4-5 phút, render video) dễ bị cắt kết nối giữa chừng. Nên dùng:

- `"async": true` → nhận `202` + `jobId`, rồi hỏi `GET /api/v1/jobs/:id`.
- Header `x-idempotency-key` → gọi lại cùng key sẽ **nhận lại kết quả cũ**, không gen thêm.
- Không gửi key: request y hệt đang chạy sẽ chờ chung; vừa xong mà client đã ngắt thì lần gửi lại nhận luôn kết quả (trong 30 phút).
- `"returnB64": false` để response nhẹ, chỉ trả `url`.
- Header `x-engine` (giá trị xem ở `GET /api/v1/info`) → chỉ nhận ảnh từ engine chính; engine chính hết hạn mức thì trả `503` ngay.

Mọi response tạo ảnh có field **`engine`** cho biết engine nào đã vẽ (engine chính hay engine dự phòng).

## Endpoint chính

| Nhóm | Endpoint |
|---|---|
| Ảnh sản phẩm | `POST /generate` · `/review-pack` · `/bg-swap` · `/knowledge-pack` · `/create` · `/compare-ref` · `/qa` |
| Banner & biểu đồ | `POST /banner` · `/chart` |
| Video | `POST /auto-script` · `/html-video/render` · `/render-video` · `/render-pro` · `GET /html-video/templates` |
| Kịch bản & giọng | `POST /script` · `/script/srt` · `/tts` · `/tts/summary` · `/tts/podcast` · `/transcribe` · `/transcribe/srt` |
| Xử lý ảnh | `POST /remove-bg` · `/upscale` · `/tinypng` |
| Người mẫu & thương hiệu | `GET/POST /models` · `POST /models/:id/pose` · `/models/:id/uniform` · `GET /brands` · `GET/POST /wallpapers` |
| Thư viện | `GET /library` · `GET /image/:id?res=2k\|4k` · `DELETE /library/:id` · `GET /jobs/:id` |

> **Đã gỡ:** `POST /video` (Grok Imagine) trả `410` từ v1.13.3; `render-pro` chế độ clip Grok tự chạy chế độ ảnh + Ken Burns.

## Ví dụ

```bash
# Bộ ảnh review + ảnh Featured trong 1 lần gọi (chạy nền)
curl -X POST https://media.phatdev.net/api/v1/review-pack \
  -H 'Content-Type: application/json' -H 'x-api-token: <key>' \
  -H 'x-idempotency-key: rog-scar18-2026-10' \
  -d '{"refUrls":["https://.../anh-H1.jpg"],"spaceId":"studio","productName":"ROG Strix SCAR 18","featured":{"title":"Đánh giá ROG Strix SCAR 18"},"async":true}'
# → 202 { jobId }  → GET /api/v1/jobs/<jobId>

# Kịch bản video từ link sản phẩm (trả tiến trình dạng SSE)
curl -N -X POST https://media.phatdev.net/api/v1/auto-script \
  -H 'Content-Type: application/json' -H 'x-api-token: <key>' \
  -d '{"productUrl":"https://hungphatlaptop.com/...","brandName":"Hưng Phát Laptop"}'
```

## Mã lỗi

| Mã | Ý nghĩa | Pipeline nên |
|---|---|---|
| `400` | Tham số sai (khung ảnh, ảnh tham chiếu hỏng…) | Sửa request |
| `401` | Thiếu / sai key | Kiểm tra `x-api-token` |
| `410` | Tính năng đã gỡ | Bỏ gọi |
| `422` | Kết quả không dùng được (vd PNG trong suốt rỗng) | Thử lại với ảnh khác |
| `503` | Engine quá tải / hết hạn mức | Chờ rồi thử lại (kèm idempotency key) |