Xác thực và quy chuẩn cơ bản

Trang này là quy ước chung của tất cả API, bao gồm địa chỉ cơ sở, xác thực, định dạng yêu cầu và phản hồi, phân trang, giới hạn tần suất, tính idempotent và xử lý lỗi. Tham số và ví dụ của từng API cụ thể xem Tổng quan API cùng trang API tương ứng.

Địa chỉ cơ sở

Xác thực

Tất cả API đều dùng cùng một khóa API nền tảng:

Authorization: Bearer sk-你的APIKey
Content-Type: application/json

Có thể bỏ tiền tố Bearer (nhưng không khuyến nghị)

Thực tế kiểm chứng bốn cách viết:

Nền tảng đồng thời chấp nhận token trần, vì vậy trả về 200 không có nghĩa là client đã cấu hình đúng. Ngược lại, nếu một client trả về 401, trước tiên hãy xác nhận xem nó có bỏ sót toàn bộ header Authorization hay không, thay vì nghi ngờ chính Key. Hãy luôn dùng cách viết Bearer.

Khi khóa API bị thiếu, sai, bị vô hiệu hóa hoặc không thuộc tài khoản hiện tại, trả về HTTP 401:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)",
    "type": "new_api_error"
  }
}

Lưu ý code là chuỗi rỗng. Khi xác thực thất bại nền tảng không điền code, vì vậy đừng dùng việc code có rỗng hay không để phán đoán yêu cầu có lỗi hay không, mà nên lấy mã trạng thái HTTP làm chuẩn. request id trong message có thể lấy trực tiếp để gửi ticket.

Loại thất bại xác thực này có cấu trúc nhất quán trên mọi API, message sẽ kèm theo định danh yêu cầu, thuận tiện cho việc khắc phục.

Cấu trúc phản hồi

Nền tảng có ba bộ cấu trúc phản hồi, client phải kiểm tra đồng thời mã trạng thái HTTP và phần thân phản hồi.

API mô hình, văn bản, hình ảnh, video và âm thanh

Khi thành công trả về trực tiếp đối tượng kết quả, khi thất bại trả về HTTP không phải 2xx kèm đối tượng error:

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

Truy vấn tác vụ video là ngoại lệ: khi không tìm thấy tác vụ sẽ trả về 400, phần thân phản hồi là cấu trúc cấp cao nhất { code, message, data } (code là chuỗi task_not_exist), không phải đối tượng error nêu trên. Chi tiết xem Mã lỗi và khắc phục. Giá trị của code, type, param thay đổi theo loại lỗi, khi khắc phục hãy lấy message làm chính, đừng chỉ khớp văn bản code cố định.

API thư viện tư liệu

Cả thành công và thất bại đều dùng cấu trúc thống nhất:

{ "code": 0, "data": {}, "msg": "OK" }

{ "code": 401, "data": null, "msg": "API Key 无效或已失效" }

Khi thất bại, mã trạng thái HTTP trùng với code (400 / 401 / 404 / 429 / 502 / 503). Tư liệu chưa duyệt xong không phải lỗi, mà là trường status trong phản hồi 200 (Processing / Active / Failed).

Phân trang

Các API danh sách như nhóm tư liệu, danh sách tư liệu dùng tham số phân trang thống nhất:

data.total trong phản hồi là tổng số mục, data.page, data.page_size là tham số phân trang có hiệu lực lần này. Hãy luôn đọc total để phán đoán còn trang tiếp theo hay không, đừng dùng "số mục trả về lần này" để phán đoán.

Giới hạn tần suất và thử lại

Chỉ thử lại với 429 và 5xx tạm thời; 400, 401, 403, 404, 409 thuộc vấn đề yêu cầu hoặc quyền, thử lại sẽ không thành công.

Idempotent và gửi trùng lặp

Nền tảng không cung cấp khóa idempotent tự động xuyên API, vui lòng đảm bảo phía nghiệp vụ chỉ gửi một lần:

• Mỗi thao tác người dùng trước tiên ghi một bản ghi nghiệp vụ vào cơ sở dữ liệu riêng, rồi mới gọi API nền tảng;
• Việc gửi tác vụ video và tư liệu đều phải lưu ID do nền tảng trả về, trước khi thử lại hãy truy vấn xem đã tạo chưa;
• Khi tư liệu ở trạng thái Processing đừng gửi trùng, nếu không sẽ tạo nhiều bản tư liệu;
• Việc tính phí dựa trên tác vụ thực sự gửi thành công, gửi trùng sẽ gây tính phí trùng.

Thứ tự gọi khuyến nghị

GET  /v1/models                     选择模型，确认能力与可用性
POST /api/v1/materials/groups       需要素材时创建分组
POST /api/v1/materials/assets       提交图片，保存 asset_id
GET  /api/v1/materials/assets/{id}  轮询到 status 为 Active
POST /v1/video/generations          提交视频任务，用 asset://<id> 引用素材
GET  /v1/video/generations/{id}     轮询任务，读取结果或错误

Khuyến nghị tích hợp phía máy chủ

1. Đặt thời gian chờ hợp lý cho mỗi yêu cầu, và phân biệt "quá thời gian chờ" với "người dùng hủy";
2. Với 429 và 5xx tạm thời thực hiện thử lại lùi có số lần giới hạn, các lỗi còn lại trả thẳng về bên gọi;
3. Lưu số yêu cầu nghiệp vụ, ID mô hình, ID tư liệu, ID tác vụ và định danh yêu cầu do nền tảng trả về, thuận tiện khắc phục;
4. Đừng ghi khóa API vào log, báo cáo lỗi, tracking phía frontend hoặc ảnh chụp màn hình;
5. Với tệp lớn ưu tiên dùng địa chỉ HTTPS công khai của lưu trữ đối tượng hoặc tham chiếu asset:// của thư viện tư liệu, đừng nhồi tệp lớn vào phần thân yêu cầu.

Bước tiếp theo