Mức sử dụng

GET /v1/usage trả về toàn bộ hạn mức tài khoản của bạn cùng phần đã dùng trong chu kỳ thanh toán hiện tại: gói, mốc thời gian chu kỳ và một bộ đếm cho từng loại tài nguyên. Dùng nó để hiển thị widget mức sử dụng, quyết định có gửi job FFmpeg hay không, hoặc kiểm tra còn bao nhiêu slot Profile trước khi tạo connect link.

Đăng bài không giới hạn trên mọi gói trả phí (xem Bài đăng), nên uploads.limit luôn là null, bộ đếm used vẫn chạy như một số liệu ghi nhận, không phải hạn mức.

Request

curl https://api.madiad.com/v1/usage \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Endpoint này chỉ hoạt động trong phạm vi tài khoản sở hữu API key: không nhận tham số nào và không bao giờ trả về số liệu của tài khoản khác. Đây là request GET, không tiêu tốn phút FFmpeg hay lượt đăng nào, chỉ tính vào rate limit mỗi phút.

Response

{
  "plan": { "id": "growth", "name": "Growth", "price_vnd_monthly": 390000 },
  "status": "active",
  "period": { "start": "2026-07-07", "renews_on": "2026-08-07", "expires_on": null },
  "uploads": { "used": 180, "limit": null, "remaining": null },
  "ffmpeg_minutes": { "used": 12, "limit": 150, "remaining": 138 },
  "profiles": { "used": 4, "limit": 4, "remaining": 0 },
  "direct_messages": {
    "used": 0,
    "limit": 0,
    "remaining": 0,
    "day": "2026-07-20",
    "included": false
  },
  "api_keys": { "used": 2, "limit": null, "remaining": null },
  "features": { "schedule": true, "queue": true, "analytics": true, "webhooks": true }
}

Bộ đếm

Mọi tài nguyên có hạn mức đều dùng chung ba field:

Field	Ý nghĩa
`used`	Đã dùng trong chu kỳ hiện tại (riêng `direct_messages` là đã dùng trong ngày hôm nay).
`limit`	Hạn mức. `null` nghĩa là không giới hạn. `0` nghĩa là gói của bạn không bao gồm tài nguyên đó.
`remaining`	`limit - used`, không xuống dưới 0. Là `null` khi `limit` là `null`.

Hãy hiểu limit: null là không giới hạn, không phải 0: fallback remaining ?? 0 sẽ hiển thị sai với người dùng của bạn rằng họ đã hết hạn mức.

Các field

Field	Ý nghĩa
`plan`	Id, tên hiển thị và giá theo tháng (VND) của gói đang hoạt động (`null` với gói Custom).
`status`	Trạng thái tài khoản. Ở response này luôn là `active`: tài khoản `expired` hoặc `banned` bị trả `403` trước khi endpoint chạy (xem phần lỗi bên dưới).
`period.start`	Ngày đầu tiên của chu kỳ hiện tại, dạng `YYYY-MM-DD`.
`period.renews_on`	Ngày chu kỳ chuyển sang kỳ mới và các bộ đếm được reset.
`period.expires_on`	Ngày kết thúc thời hạn đã thanh toán nếu có, ngược lại là `null`.
`uploads`	Số bài đã đăng trong chu kỳ. `limit` là `null` trên mọi gói trả phí.
`ffmpeg_minutes`	Số phút FFmpeg trong chu kỳ. Hạn mức tính cho cả tài khoản: mọi thương hiệu dùng chung hạn mức này.
`profiles`	Số Profiles đã kết nối so với giới hạn của gói.
`direct_messages`	Số DM hôm nay. `included: false` nghĩa là gói của bạn không có tính năng tương tác.
`api_keys`	Số key đang hoạt động (chưa thu hồi).
`features`	Các cờ tính năng của gói đang hoạt động.

Mốc thời gian chu kỳ

Chu kỳ của bạn được neo theo ngày kích hoạt gói, tính theo giờ Việt Nam (UTC+7), không phải ngày mùng 1 của tháng dương lịch. Gói kích hoạt ngày 7 sẽ reset vào ngày 7 hằng tháng. Nếu ngày neo không tồn tại trong tháng ngắn hơn, hệ thống lùi về ngày cuối cùng của tháng đó. period.start và period.renews_on luôn báo đúng ngày thực tế, nên hãy đọc hai field này thay vì tự tính mốc đầu/cuối tháng.

Kiểm tra trước khi thao tác

# Chỉ gửi job FFmpeg nếu còn phút (null = không giới hạn).
REMAINING=$(curl -s https://api.madiad.com/v1/usage \
  -H "Authorization: Bearer $MADIAD_API_KEY" | jq '.ffmpeg_minutes.remaining')

if [ "$REMAINING" = "null" ] || [ "$REMAINING" -gt 0 ]; then
  echo "Có thể gửi job"
fi

Lỗi

Status	Code	Ý nghĩa
`401`	`unauthorized`	API key thiếu hoặc không hợp lệ.
`403`	`forbidden`	Tài khoản đang ở trạng thái `expired` hoặc `banned`. Tài khoản hết hạn sẽ đăng bài lại ngay khi khoản gia hạn được ghi nhận.
`429`	`rate_limited`	Vượt giới hạn số request mỗi phút.

Xem Lỗi để biết danh sách đầy đủ.

Bắt đầu

Khái niệm

Tích hợp

Request

Response

Bộ đếm

Các field

Mốc thời gian chu kỳ

Kiểm tra trước khi thao tác

Lỗi

​Request

​Response

​Bộ đếm

​Các field

​Mốc thời gian chu kỳ

​Kiểm tra trước khi thao tác

​Lỗi

Request

Response

Bộ đếm

Các field

Mốc thời gian chu kỳ

Kiểm tra trước khi thao tác

Lỗi