Tổng quan
Kết nối ứng dụng với chat, tệp, hội thoại và voice của trợ lý.
Developer API cho phép backend gọi một trợ lý qua REST, Server-Sent Events (SSE) và WebSocket. API key xác định trợ lý; ứng dụng cung cấp external_user_id để tách hội thoại và memory cho từng người dùng cuối.
Developer API v1 đang ở giai đoạn Preview. Contract có thể thay đổi trước khi API được công bố GA.
Bắt đầu nhanh
Tạo API key và gửi chat request đầu tiên.
API key và bảo mật
Scopes, billing, dữ liệu người dùng và quản lý key.
API reference
OpenAPI, AsyncAPI, endpoints và compatibility policy.
Chat API
Chat, streaming, tệp, hội thoại và feedback.
Voice API
Voice session, events, audio và reconnect.
Luồng tích hợp khuyến nghị
- Client đăng nhập vào backend của ứng dụng bạn.
- Backend ánh xạ user đã xác thực sang một
external_user_idổn định. - Backend gọi Developer API bằng API key lưu trong secret manager.
- Backend trả JSON hoặc chuyển tiếp SSE cho client. Với voice, backend chỉ trả session token ngắn hạn và
websocket_url.
Không nhận external_user_id tùy ý từ client rồi chuyển thẳng sang Assistant Core. Backend phải lấy giá trị này từ user/session đã xác thực để một người dùng không thể truy cập hội thoại của người khác.
Endpoint và scope
| Endpoint | Scope | Dùng để |
|---|---|---|
POST /v1/chat/responses | chat:write | Tạo response dạng JSON hoặc stream SSE. |
GET /v1/responses/{id} | chat:write | Lấy lại response đã hoàn tất. |
POST /v1/files | files:write | Upload tệp cho một external user. |
GET /v1/conversations/{id} | conversations:read | Lấy metadata hội thoại. |
GET /v1/conversations/{id}/messages | conversations:read | Đọc lịch sử tin nhắn có phân trang. |
POST /v1/messages/{id}/feedback | feedback:write | Gửi đánh giá up hoặc down. |
POST /v1/voice/sessions | voice:connect | Tạo token ngắn hạn để mở Voice WebSocket. |
DELETE /v1/users/{external_user_id} | users:delete | Xóa dữ liệu của một end user. |
Chọn cách tích hợp
| Nhu cầu | Nên dùng |
|---|---|
| Thêm giao diện chat dựng sẵn vào website | Widget web |
| Xây UI, workflow hoặc backend automation riêng | Developer API |
| Xây voice client và tự quản lý audio | Voice API |
| Dùng trang chat và voice có sẵn trên domain của bạn | Ứng dụng Web |
API key là secret phía máy chủ. Không đặt key trong browser, ứng dụng mobile, source code, URL hoặc log. Browser voice chỉ nhận session token ngắn hạn, dùng một lần.
Đường dẫn triển khai
- Bắt đầu bằng request chat không streaming để kiểm tra key, plan và identity mapping.
- Dùng API reference làm nguồn chính thức cho schema và code generation.
- Thêm SSE, upload tệp và lịch sử hội thoại khi luồng cơ bản đã hoạt động.
- Chỉ triển khai Voice API khi client đã xử lý được capture, codec và playback audio.
- Trước khi production, áp dụng quản lý key và retry/rate limit.