nguynbon03/rest-api-standard

REST API Standard — Viết API chuẩn quốc tế

Chuẩn hóa mọi API mà Bon tạo ra: tham số rõ ràng, mã trả về đầy đủ, tài liệu tự động.

Cấu trúc API chuẩn

Base URL

https://api.yourdomain.com/v1

Versioning

• Luôn có version trong URL: /v1/, /v2/
• Khi thay đổi lớn → tạo version mới, giữ version cũ hoạt động

Authentication

Authorization: Bearer sk_live_xxxxxxxxxxxx

• Mọi endpoint đều cần API key (trừ health check)
• API key có prefix: sk_live_ (production), sk_test_ (sandbox)

Cấu trúc Response chuẩn

Thành công

{
  "code": 200,
  "message": "Thành công",
  "data": {
    "job_id": "job_abc123",
    "status": "processing",
    "estimated_time": 120
  },
  "request_id": "req_xyz789"
}

Lỗi

{
  "code": 400,
  "message": "Thiếu tham số bắt buộc: image",
  "error": {
    "type": "validation_error",
    "field": "image",
    "detail": "Phải gửi ảnh đầu vào (file upload hoặc URL)"
  },
  "request_id": "req_xyz789"
}

Mã trả về chuẩn

| Mã | Ý nghĩa | Khi nào | |----|---------|---------| | 200 | Thành công | Request xử lý xong | | 201 | Đã tạo | Job đã được tạo, đang xử lý | | 400 | Yêu cầu không hợp lệ | Thiếu tham số, sai format | | 401 | Chưa xác thực | Thiếu hoặc sai API key | | 402 | Hết credits | Tài khoản hết credits | | 403 | Bị cấm | Không có quyền truy cập | | 404 | Không tìm thấy | Job/resource không tồn tại | | 429 | Quá giới hạn | Vượt rate limit | | 500 | Lỗi server | Lỗi nội bộ | | 503 | Không khả dụng | Server đang bảo trì |

Upload File

Cách 1: Upload trực tiếp (multipart/form-data)

POST /v1/files/upload
Content-Type: multipart/form-data

file: <binary>
type: image|video|audio

Response:

{
  "code": 200,
  "data": {
    "file_id": "file_abc123",
    "url": "https://cdn.example.com/uploads/file_abc123.mp4",
    "type": "video",
    "size": 15728640,
    "duration": 10.5
  }
}

Cách 2: Upload từ URL

POST /v1/files/upload-url
{
  "url": "https://example.com/video.mp4",
  "type": "video"
}

→ Hệ thống tự download từ URL, trả về file_id

Giới hạn file

| Loại | Kích thước tối đa | Định dạng | |------|-------------------|-----------| | Ảnh | 30MB | jpg, png, webp | | Video | 100MB | mp4, mov, avi | | Audio | 50MB | mp3, wav, aac |

Nhận kết quả

Cách 1: Polling (khuyến nghị)

GET /v1/jobs/{job_id}

Response:

{
  "code": 200,
  "data": {
    "job_id": "job_abc123",
    "status": "completed",
    "progress": 100,
    "result": {
      "video_url": "https://cdn.example.com/results/output.mp4",
      "duration": 5.0,
      "resolution": "1080x1920"
    },
    "created_at": "2026-03-21T10:00:00Z",
    "completed_at": "2026-03-21T10:02:15Z"
  }
}

Trạng thái job: | Status | Ý nghĩa | |--------|---------| | pending | Đang chờ xử lý | | processing | Đang xử lý | | completed | Hoàn thành, có kết quả | | failed | Thất bại |

Cách 2: Webhook (nâng cao)

POST /v1/motion/generate
{
  "image": "file_abc123",
  "video": "file_def456",
  "webhook_url": "https://your-server.com/callback"
}

→ Khi xong, hệ thống POST kết quả đến webhook_url

Endpoint mẫu cho Video Generation

POST /v1/motion/generate
{
  "image": "file_abc123",        // file_id hoặc URL ảnh đầu vào
  "video": "file_def456",        // file_id hoặc URL video tham chiếu
  "mode": "motion_control",      // motion_control | lip_sync | ...
  "duration": 5,                 // thời lượng video (giây)
  "aspect_ratio": "9:16",        // tỷ lệ khung hình
  "webhook_url": ""              // (tùy chọn) URL callback
}

Các mẫu triển khai

Code mẫu:

• references/api-response.py — Chuẩn hóa response format
• references/file-handler.py — Upload file + download từ URL
• references/job-manager.py — Quản lý job: tạo, theo dõi, trả kết quả
• references/api-docs-example.md — Mẫu tài liệu API đầy đủ

Quy tắc

• MỌI response đều phải có code, message, data, request_id
• MỌI endpoint đều cần authentication (trừ health check)
• MỌI file upload đều phải validate: kích thước, định dạng, nội dung
• Input hỗ trợ CẢ file upload LẪN URL (hệ thống tự download)
• Job dài (>30s) → trả job_id ngay, client polling hoặc webhook
• Rate limit: trả header X-RateLimit-Remaining, X-RateLimit-Reset
• Swagger docs tự động tại /docs
• Luôn ghi log: request_id, thời gian, kết quả

Xem thêm: Tham khảo https://tramsangtao.com/docs