Quy ước chung

Trang này mô tả các quy tắc gọi chung cho các endpoint của AGTCloud API. Các trường, trạng thái và cấu trúc phản hồi cụ thể vẫn theo trang API Reference tương ứng.

Địa chỉ API và Base URL

Địa chỉ API dùng trên trang này là https://api.agtcloud.cn; SDK tương thích OpenAI sử dụng Base URL https://api.agtcloud.cn/v1.

Xác thực

Phần lớn API được bảo vệ sử dụng Bearer API Key:

Authorization: Bearer your-api-key

Anthropic Messages sử dụng Header xác thực riêng và yêu cầu cung cấp phiên bản API:

x-api-key: your-api-key
anthropic-version: 2023-06-01

Header tùy chọn như anthropic-beta và yêu cầu xác thực của các giao thức khác được mô tả trên trang Endpoint tương ứng.

Đến API Keys để tạo và quản lý token. Chỉ gửi API Key khi gọi; không dùng mật khẩu bảng điều khiển, Cookie, token quản trị hoặc Key của nhà cung cấp phía trên.

Dưới đây là một yêu cầu Chat Completions tối thiểu:

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  --request POST \
  --header 'Authorization: Bearer your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Xin chào"
      }
    ]
  }'

Xem cách tạo, luân chuyển và lưu API Key trong môi trường sản xuất tại API Key, Base URL và xác thực.

Đặt tham số yêu cầu ở đâu

Trang endpoint hiển thị riêng các trường theo vị trí tham số:

Tham số Path cần được mã hóa URL trước. Bỏ qua tham số tùy chọn không sử dụng; không dùng chuỗi rỗng để thay thế mọi giá trị tùy chọn.

Content-Type và định dạng dữ liệu

Khi dùng Multipart, không đặt cứng boundary; để trình duyệt, SDK hoặc HTTP client tạo Content-Type đầy đủ dựa trên nội dung biểu mẫu.

ID mô hình

MODEL_ID trong ví dụ Reference là giá trị giữ chỗ, cần thay bằng ID mô hình khả dụng với API Key hiện tại. Có thể tìm mô hình tại Danh mục mô hình, hoặc nhập Key trong Try It để lấy danh sách mô hình mà Key đó trả về.

Mô hình, giao thức và nhà cung cấp phía trên là các khái niệm khác nhau:

• ID mô hình xác định mô hình mục tiêu của yêu cầu.
• Endpoint xác định giao thức và cấu trúc tin nhắn phía máy khách sử dụng.
• Một mô hình có thể cung cấp nhiều giao thức hoặc chỉ hỗ trợ một phần trường.

Phân tích phản hồi

Nên xử lý phản hồi theo thứ tự sau:

Phản hồi dạng luồng

API SSE liên tục gửi nhiều sự kiện hoặc khối dữ liệu trong một phản hồi HTTP. Phía máy khách phải đọc nội dung tăng dần, thay vì chờ kết nối đóng rồi phân tích toàn bộ phản hồi thành một đối tượng JSON.

• Nhận diện sự kiện hoặc dấu kết thúc theo mô tả của endpoint.
• Xử lý riêng nội dung tăng dần, gọi công cụ, Usage và sự kiện lỗi.
• Khi mạng gián đoạn, không mặc định xem nội dung đã nhận là kết quả hoàn chỉnh.
• Mỗi giao thức có cấu trúc sự kiện dạng luồng riêng; dùng định nghĩa sự kiện của endpoint hiện tại.

Tác vụ bất đồng bộ

Các API như video và Midjourney thường trả về định danh tác vụ trước, rồi dùng API truy vấn để lấy tiến độ và kết quả cuối cùng:

Gửi tác vụ → Lưu ID tác vụ → Truy vấn trạng thái → Kiểm tra trạng thái kết thúc → Đọc kết quả

Tên trường ID tác vụ, giá trị trạng thái và đường dẫn truy vấn phụ thuộc vào giao thức cụ thể. Không dùng lẫn id, task_id, video_id hoặc giá trị trạng thái giữa các API.

Đặt khoảng thời gian truy vấn và tổng thời gian chờ khi thăm dò, rồi dừng khi tác vụ thành công, thất bại hoặc bị hủy. Nếu yêu cầu gửi tác vụ hết thời gian chờ nhưng tác vụ có thể đã được tạo, hãy xác nhận trạng thái trước để tránh tạo tác vụ tính phí trùng lặp.

Trạng thái HTTP và thử lại

Dưới đây là hướng xử lý chung; cấu trúc lỗi cụ thể theo phản hồi thực tế của endpoint:

Không thử lại vô hạn với mọi lỗi. Lỗi tham số, xác thực hoặc quyền chỉ nên gửi lại sau khi đã sửa; với yêu cầu có thể tạo tác dụng phụ như tạo tác vụ, cần xác định xem đã gửi thành công hay chưa.

Xem các bước chẩn đoán đầy đủ hơn tại Lỗi và khắc phục sự cố.

Usage, thời gian và trường mở rộng

• Việc trường Usage có tồn tại hay không và tên trường phụ thuộc vào giao thức cùng mô hình; phía máy khách phải chấp nhận giá trị rỗng hoặc trường bị thiếu.
• Trường thời gian có thể dùng giây Unix, mili giây Unix hoặc chuỗi thời gian; phải phân tích theo Schema của endpoint.
• Trường mở rộng của nhà cung cấp thường chỉ áp dụng cho một số mô hình, không phải khả năng chung của tất cả mô hình.
• Khi phân tích phản hồi, phía máy khách nên chấp nhận trường mới không quan trọng để tránh việc thêm trường tương thích khiến toàn bộ quá trình phân tích thất bại.

An toàn và log

• API Key dài hạn nên lưu trên máy chủ đáng tin cậy hoặc hệ thống quản lý khóa; không tích hợp sẵn Key trong frontend trong môi trường production, ứng dụng máy tính hoặc di động.
• Try It trong tài liệu chỉ dùng cho việc thử tạm thời trong trình duyệt do khách hàng chủ động thực hiện; không dùng Key dài hạn của môi trường production trên thiết bị dùng chung.
• Không ghi Key vào kho mã công khai, ảnh chụp màn hình, log hoặc phiếu hỗ trợ.
• Che dữ liệu nhạy cảm trong Prompt, địa chỉ tệp, thông tin tài khoản và dữ liệu yêu cầu, phản hồi trước khi gửi tài liệu chẩn đoán.
• Vô hiệu hóa hoặc xóa ngay Key không còn dùng hay nghi bị lộ và cập nhật các dịch vụ sử dụng Key đó.

Đọc tiếp: API Reference · Bắt đầu nhanh · Lỗi và khắc phục sự cố