Tổng quan

Quy ước API

Lỗi

Mọi lỗi trả về cùng một khuôn:

json

{
  "success": false,
  "errorCode": "INVALID_DPI",
  "error": "dpi must be between 1 and 1200.",
  "details": [
    {
      "field": "dpi",
      "code": "INVALID_DPI",
      "message": "dpi must be between 1 and 1200.",
      "params": { "min": 1, "max": 1200 }
    }
  ],
  "requestId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

successboolean
Luôn là false khi lỗi.
errorCodestring
Mã để code rẽ nhánh. Lỗi nào cũng có.
errorstring
Câu cho người đọc — là tiếng Anh khi request có header X-Api-Key. Câu có thể đổi — đừng so khớp theo câu.
detailsobject[]
Chỉ có khi lỗi: lỗi cụ thể theo từng trường.
Hiện thuộc tính conẨn thuộc tính con
- fieldstring
  Trường của request bị lỗi, nếu có.
- codestring
  Mã lỗi của trường này.
- messagestring
  Câu cho người đọc.
- paramsobject
  Các số liệu trong câu (min, max, retryAfter…), để tự dựng câu của bạn.
requestIdstring
Chỉ có khi lỗi: giống header X-Request-Id.

Mọi mã lỗi, kèm mã HTTP, câu tiếng Anh và có nên thử lại hay không, có ở GET /v2/errors (không cần key) — và ở trang Mã lỗi.

Mã request

Mọi response có header X-Request-Id; khi lỗi, body có thêm requestId cùng giá trị. Gửi kèm mã này khi báo lỗi — nhờ nó chúng tôi tìm đúng lượt gọi của bạn.

Giới hạn gọi

6.000 request mỗi phút cho mỗi API key; riêng upload ảnh tham chiếu (POST /images/presign) tối đa 30 lượt mỗi phút. Response nào cũng cho biết bạn đang ở đâu:

Header	Ý nghĩa
X-RateLimit-Limit	Số request được phép mỗi phút
X-RateLimit-Remaining	Số request còn lại trong phút này
X-RateLimit-Reset	Lúc bộ đếm bắt đầu lại, tính bằng giây Unix
Retry-After	Chỉ có ở 429: số giây cần chờ

Vượt giới hạn, lượt gọi trả 429 với errorCode RATE_LIMITED. Chờ đủ Retry-After giây rồi gửi lại.

Phân trang

Danh sách nhận page (từ 1) và pageSize — gửi limit cũng được, cùng nghĩa. Tổng số nằm ở header X-Total-Count.

Danh sách	pageSize mặc định	Tối đa	Không gửi page, pageSize
GET /characters	50	200	Trả hết
GET /user-assets	50	200	Trả hết
GET /jobs	10	100	10 job đầu
GET /account/transactions	20	100	20 giao dịch đầu

GET /jobs trả tổng số trong body (total) thay vì header.

Chống tạo trùng

POST /images/generations và POST /publishing/posts nhận một khoá, ở header Idempotency-Key hoặc trường idempotencyKey trong body, giữ trong 24 giờ:

Bạn gửi	Kết quả
Cùng khoá, cùng nội dung	Job hoặc bài cũ, kèm idempotentReplay: true — không tạo, không trừ tiền lần hai
Cùng khoá, nội dung khác	422 IDEMPOTENCY_KEY_REUSED
Header và trường body khác khoá nhau	422 VALIDATION_ERROR
Không gửi khoá	Luôn tạo job hoặc bài mới

Mỗi thao tác một khoá mới (ví dụ một UUID). Chỉ gửi lại khoá cũ khi thử lại đúng request đó.

Mã id

Mọi id là chuỗi mờ có tiền tố — sa_… (tài khoản mạng xã hội), pp_… (nền tảng của bài đăng), tx_… (giao dịch), acct_… (tài khoản). Lưu và gửi lại nguyên văn; đừng so sánh, sắp xếp hay tính toán trên id.

Trang trướcXác thực Trang sauMã lỗi