# Video Gateway API — v1.1

Base URL mặc định: `http://localhost:18611`. API nhận JSON và tạo video bất đồng bộ. Gateway cần muse2api hoạt động và có tài khoản khả dụng. API không cung cấp đăng nhập muse2api, quản trị tài khoản, chat hoặc tạo ảnh.

- Swagger tương tác: `/docs` — nhấn **Authorize**, nhập riêng khóa gateway.
- ReDoc: `/redoc`.
- OpenAPI: `/openapi.json`. File `openapi.json` trong repo là bản xuất từ app, không sửa tay.
- Hướng dẫn này: `/api-guide`.

## Xác thực

Các endpoint `/v1/*` yêu cầu:

```http
Authorization: Bearer YOUR_GATEWAY_API_KEY
```

Dùng `GATEWAY_API_KEY`, không dùng khóa muse2api. Khóa upstream được cấu hình trên server bằng `UPSTREAM_API_KEY`. Gateway không trả khóa trong API. Tất cả client dùng chung khóa có cùng quyền truy cập tác vụ và media; không có phân quyền theo người dùng.

Ví dụ thiết lập biến cho lệnh cURL (nhập khóa của bạn, không commit vào mã nguồn):

```bash
export VIDEO_GATEWAY_URL=http://localhost:18611
export GATEWAY_API_KEY='YOUR_GATEWAY_API_KEY'
```

## Endpoint

| Phương thức | Đường dẫn | Thành công | Nội dung |
| --- | --- | --- | --- |
| GET | `/health` | 200 | Tiến trình gateway; không cần khóa, không kiểm tra upstream |
| GET | `/v1/models` | 200 | Model gateway hỗ trợ; không xác nhận còn quota |
| POST | `/v1/videos` | 202 | Tạo tác vụ |
| GET | `/v1/videos/{task_id}` | 200 | Kiểm tra tiến độ |
| GET | `/v1/media/{name}` | 200 | Tải bytes video |

Các đường dẫn tương thích `POST /v1/videos/generations` và `GET /v1/videos/generations/{task_id}` có cùng dữ liệu và mã phản hồi với đường dẫn chính. Đây là API JSON của gateway; không hỗ trợ upload multipart hoặc toàn bộ API của OpenAI.

## 1. Xem model

```bash
curl --fail-with-body "$VIDEO_GATEWAY_URL/v1/models" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
```

```json
{"object":"list","data":[{"id":"muse-video","object":"model","owned_by":"muse"}]}
```

## 2. Tạo video

```bash
curl --fail-with-body "$VIDEO_GATEWAY_URL/v1/videos" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"muse-video","prompt":"Một chiếc thuyền trên hồ lúc bình minh","duration":5,"aspect_ratio":"16:9"}'
```

Body JSON:

| Trường | Kiểu | Mặc định / giới hạn |
| --- | --- | --- |
| `prompt` | string, bắt buộc | 1–20000 ký tự |
| `model` | string | `muse-video`; dùng model này cho video |
| `duration` | integer hoặc null | 1–60 giây; bỏ trống để upstream quyết định |
| `size` | string hoặc null | Chuyển tiếp muse2api; ví dụ `16:9` |
| `aspect_ratio` | string hoặc null | Ví dụ `16:9`, `9:16` |
| `resolution` | string hoặc null | Gợi ý độ phân giải cho upstream |
| `timeout` | integer hoặc null | 1–1800 giây; thời gian tạo ở upstream |
| `extra` | string hoặc null | Chỉ dẫn bổ sung |
| `reference_image` | string hoặc null | URL hoặc data URL ảnh tham chiếu |
| `image_url` | string, object hoặc null | URL/data URL hoặc `{"url":"https://…"}` |
| `image` | string, object hoặc null | Dạng ảnh tương thích, như `image_url` |

Ảnh được chọn theo thứ tự `reference_image` → `image_url` → `image`; chỉ gửi một ảnh để tránh nhầm lẫn. Thời lượng, tỉ lệ và độ phân giải là chỉ dẫn cho upstream, không phải bảo đảm chính xác của model. Tham số ảnh theo định dạng muse2api; gateway không upload tệp từ máy client.

Ví dụ ảnh thành video:

```json
{
  "prompt": "Máy quay tiến chậm, lá cây chuyển động nhẹ",
  "duration": 5,
  "aspect_ratio": "9:16",
  "image_url": {"url": "https://example.com/reference.jpg"}
}
```

Phản hồi HTTP **202 Accepted** (ID minh họa):

```json
{"id":"task_xyz789","task_id":"task_xyz789","status":"queued","progress":10}
```

Lưu ID ngay. HTTP 202 chỉ xác nhận tác vụ được nhận, chưa xác nhận tạo video thành công. Không có endpoint liệt kê, hủy hoặc xóa tác vụ trong gateway.

## 3. Theo dõi tác vụ

```bash
curl --fail-with-body "$VIDEO_GATEWAY_URL/v1/videos/task_xyz789" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
```

Đang xử lý:

```json
{"id":"task_xyz789","status":"processing","progress":45}
```

Hoàn tất:

```json
{
  "id": "task_xyz789",
  "status": "completed",
  "progress": 100,
  "url": "/v1/media/vid_xyz789.mp4",
  "video": {"url": "/v1/media/vid_xyz789.mp4"}
}
```

Thất bại vẫn trả HTTP **200**, vì việc truy vấn trạng thái thành công:

```json
{"id":"task_xyz789","status":"failed","progress":15,"error":"Tạo video thất bại. Kiểm tra tài khoản hoặc nhật ký muse2api."}
```

Poll mỗi 4 giây. Dừng ở `completed` hoặc `failed`. Nếu mất kết nối khi poll, có thể gọi GET lại với cùng ID. Các trạng thái upstream `success`, `succeeded`, `done` được chuẩn hóa thành `completed`. Tác vụ và tệp do upstream lưu, có thể bị xóa tại upstream.

## 4. Tải video

Dùng đúng đường dẫn `url` trả về, ghép với base URL gateway:

```bash
curl --fail-with-body "$VIDEO_GATEWAY_URL/v1/media/vid_xyz789.mp4" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -o video.mp4
```

Phản hồi là bytes media, thường `Content-Type: video/mp4`. Khóa phải nằm trong header; không có URL tải công khai hoặc khóa trên query string. Trình duyệt không gắn được Bearer key qua `<video src>`: dùng fetch có Authorization rồi tạo blob URL như giao diện gateway. Endpoint hiện chưa hỗ trợ Range/resume tải.

## Lỗi và retry

| HTTP | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| 400 | Upstream từ chối dữ liệu / tên media sai | Sửa dữ liệu |
| 401 | Thiếu hoặc sai gateway key | Kiểm tra khóa và header |
| 404 | Không có tác vụ hoặc media | Kiểm tra ID, upstream và thời gian lưu |
| 409 | Xung đột upstream | Kiểm tra trạng thái trước khi gửi lại |
| 422 | JSON/kiểu/giới hạn tham số không hợp lệ, hoặc upstream từ chối dữ liệu | Sửa request |
| 429 | Upstream giới hạn lượt | Chờ trước khi thử lại |
| 502 | Không kết nối được upstream, upstream lỗi hoặc trả dữ liệu sai | Kiểm tra muse2api và cấu hình |
| 504 | Upstream quá thời gian HTTP chờ | Với POST, kết quả nhận tác vụ có thể chưa xác định |

Lỗi HTTP thường có dạng `{"detail":"Thông báo lỗi"}`. Lỗi validate cục bộ HTTP 422 có `detail` là danh sách gồm `loc`, `msg`, `type` và thông tin validation liên quan. Nội dung lỗi nội bộ của upstream được ẩn.

Timeout HTTP gateway là 30 giây, kết nối là 5 giây. Đây là giới hạn chờ phản hồi tạo/poll, khác `timeout` trong body dành cho tác vụ tạo video. Lỗi trong khi stream media đã bắt đầu có thể khiến tải bị ngắt mà không trả JSON lỗi.

**Không tự retry POST khi mất kết nối/502/504:** upstream có thể đã nhận và tạo tác vụ. Gateway chưa hỗ trợ idempotency key. Nếu đã nhận ID thì tiếp tục poll ID đó. Nếu chưa nhận ID, kiểm tra tác vụ tại muse2api trước khi quyết định tạo lại. GET có thể thử lại với khoảng nghỉ.

## Ví dụ Python (server)

Cài `httpx`, đặt hai biến môi trường như phía trên. Ví dụ đặt deadline theo dõi 35 phút; khi hết thời gian, giữ ID được in ra để tiếp tục kiểm tra.

```python
import os
import time
import httpx

base = os.getenv("VIDEO_GATEWAY_URL", "http://localhost:18611").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["GATEWAY_API_KEY"]}
with httpx.Client(base_url=base, headers=headers, timeout=45) as client:
    response = client.post("/v1/videos", json={
        "prompt": "Một chiếc thuyền trên hồ lúc bình minh",
        "duration": 5, "aspect_ratio": "16:9",
    })
    response.raise_for_status()  # Không tự gửi lại POST nếu gặp lỗi.
    task_id = response.json()["id"]
    print("Task:", task_id)
    deadline = time.monotonic() + 35 * 60
    while time.monotonic() < deadline:
        response = client.get(f"/v1/videos/{task_id}")
        response.raise_for_status()
        task = response.json()
        if task["status"] == "failed":
            raise RuntimeError(task.get("error", "Tạo video thất bại"))
        if task["status"] == "completed":
            with client.stream("GET", task["url"]) as media:
                media.raise_for_status()
                with open("video.mp4", "wb") as output:
                    for chunk in media.iter_bytes():
                        output.write(chunk)
            break
        time.sleep(4)
    else:
        raise TimeoutError(f"Tiếp tục theo dõi tác vụ {task_id} sau")
```

## Ví dụ JavaScript (Node.js 20+, server)

```javascript
import {writeFile} from 'node:fs/promises';

const base = (process.env.VIDEO_GATEWAY_URL || 'http://localhost:18611').replace(/\/$/, '');
if (!process.env.GATEWAY_API_KEY) throw new Error('Thiếu GATEWAY_API_KEY');
const headers = {Authorization: `Bearer ${process.env.GATEWAY_API_KEY}`};
async function request(path, options = {}) {
  const response = await fetch(base + path, {
    ...options,
    headers: {...headers, ...options.headers},
    signal: AbortSignal.timeout(45000),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  return response;
}
const created = await (await request('/v1/videos', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({prompt: 'Một chiếc thuyền trên hồ', duration: 5}),
})).json();
console.log('Task:', created.id);
const deadline = Date.now() + 35 * 60 * 1000;
let completed = false;
while (Date.now() < deadline) {
  const task = await (await request(`/v1/videos/${encodeURIComponent(created.id)}`)).json();
  if (task.status === 'failed') throw new Error(task.error || 'Tạo video thất bại');
  if (task.status === 'completed') {
    const media = await request(task.url);
    await writeFile('video.mp4', Buffer.from(await media.arrayBuffer()));
    completed = true;
    break;
  }
  await new Promise(resolve => setTimeout(resolve, 4000));
}
if (!completed) throw new Error(`Tiếp tục theo dõi tác vụ ${created.id} sau`);
```

## Ứng dụng web và CORS

Gọi từ server không cần CORS. Nếu ứng dụng web khác origin gọi trực tiếp gateway, đặt trong `video-gateway/.env`:

```dotenv
GATEWAY_CORS_ORIGINS=http://localhost:3000,https://studio.example.com
```

Origin không có dấu `/` cuối đường dẫn. Chạy lại `docker compose up -d` trong thư mục gateway để áp dụng. Mặc định không bật CORS cho origin khác. CORS không thay thế xác thực: mọi request `/v1/*` vẫn cần Bearer key.

Trình duyệt chỉ nên dùng khóa do người dùng nhập cho phiên đang mở; ứng dụng public nên gọi qua backend của mình để giữ gateway key phía server. Không nhúng khóa cố định vào bundle JavaScript công khai.

Docker mặc định bind `0.0.0.0:18611`; truy cập từ máy khác bằng `http://IP_SERVER:18611`, hoặc địa chỉ HTTPS của reverse proxy. Bản Docker gộp đã khởi động muse2api bên trong container; vẫn cần thêm tài khoản khả dụng tại cổng quản trị 18610. Chế độ external cần kết nối tới upstream riêng.


## Tạo ảnh

Dùng cùng `Authorization: Bearer <GATEWAY_API_KEY>`. Model: `muse-image`.

- `POST /v1/images/generations`: tạo ảnh đồng bộ, HTTP 200 với `{created, data: [{url}]}`; `response_format: "b64_json"` trả `b64_json` thay URL. HTTP có thể chờ tới 630 giây; cần cấu hình timeout client/proxy phù hợp.
- `POST /v1/images/tasks`: tạo tác vụ, HTTP 202 với `id`, `status`, `progress`.
- `GET /v1/images/tasks/{id}`: theo dõi tới `completed` hoặc `failed`. Khi hoàn tất, đọc `data[].url` hoặc `data[].b64_json`.
- `POST /v1/images/generations` với `"async": true` cũng trả tác vụ HTTP 202.

Ví dụ tạo tác vụ (khuyến nghị):

```bash
curl http://IP_SERVER:18611/v1/images/tasks \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"muse-image","prompt":"Một chú mèo bên cửa sổ","size":"1024x1024"}'
```

Poll mỗi 4 giây bằng `GET /v1/images/tasks/{id}`. URL ảnh là đường dẫn tương đối `/v1/media/...`, tải trên gateway bằng cùng Bearer key.

Ví dụ phản hồi tạo tác vụ:

```json
{"id":"image_example","task_id":"image_example","status":"queued","progress":0}
```

Thay `image_example` bằng `id` thực tế để kiểm tra trạng thái:

```bash
curl http://IP_SERVER:18611/v1/images/tasks/image_example \
  -H "Authorization: Bearer $GATEWAY_API_KEY"
```

Khi `status` là `completed`, lấy đường dẫn trong `data[0].url` rồi tải ảnh:

```bash
# Thay ten-anh.png bằng tên trong URL kết quả thực tế.
curl http://IP_SERVER:18611/v1/media/ten-anh.png \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -o image.png
```

Nếu `status` là `failed`, đọc trường `error` và dừng poll. Nếu yêu cầu `response_format: "b64_json"`, giải mã `data[0].b64_json` thay vì tải URL.

Ví dụ tạo ảnh đồng bộ:

```bash
curl --max-time 660 http://IP_SERVER:18611/v1/images/generations \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"muse-image","prompt":"Một chú mèo bên cửa sổ","response_format":"url","timeout":600}'
```

Tham số: `prompt` bắt buộc; `n` chỉ hỗ trợ 1; `size`, `aspect_ratio`, `extra` tùy chọn; `timeout` từ 1–600 giây; `image`, `reference_image` hoặc `images` (tối đa 4) làm ảnh tham chiếu. Không tự retry POST và chưa hỗ trợ idempotency key qua gateway. Bản muse2api bên ngoài phải hỗ trợ các endpoint ảnh tương ứng.