Bắt đầu nhanh
Tạo API key và gửi chat request đầu tiên từ backend.
Quickstart này tạo một chat response không streaming. Bạn cần một backend hoặc terminal; không chạy ví dụ với secret thật trong console của trình duyệt.
Developer API v1 đang ở giai đoạn Preview. Không xem contract hiện tại là cam kết GA nếu workspace của bạn chưa được cấp quyền production.
Trước khi bắt đầu
- Bạn có quyền quản lý cài đặt của trợ lý.
- Gói của owner có tính năng Developer API.
- Bạn có một mã định danh ổn định cho người dùng cuối.
1. Tạo API key
- Mở Admin Panel và chọn trợ lý.
- Vào API cho nhà phát triển.
- Chọn Tạo khóa API và đặt tên, ví dụ
Production backend. - Chỉ chọn scope
chat:writecho quickstart này. - Sao chép key
ac_…vào secret manager.
Key đầy đủ chỉ hiển thị một lần. Nếu mất key, hãy rotate để tạo key thay thế.
2. Đặt biến môi trường
export ASSISTANT_API_URL="https://api.assistantcore.com"
export ASSISTANT_API_KEY="ac_your_public_id_your_secret"
export EXTERNAL_USER_ID="customer_42"
export IDEMPOTENCY_KEY="$(uuidgen)"Dùng API origin được cung cấp cho môi trường của bạn. external_user_id phải dài 1–256 ký tự, ổn định cho cùng một người và không chứa email, số điện thoại, access token hoặc secret.
3. Gửi request đầu tiên
curl "$ASSISTANT_API_URL/v1/chat/responses" \
--request POST \
--header "Authorization: Bearer $ASSISTANT_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: $IDEMPOTENCY_KEY" \
--data "{
\"external_user_id\": \"$EXTERNAL_USER_ID\",
\"input\": \"Tóm tắt chính sách đổi trả.\",
\"stream\": false
}"Response thành công:
{
"id": "resp_01K...",
"object": "response",
"status": "completed",
"conversation_id": "a12d5e41-7ab7-4c8f-b024-c2c38b5c43f4",
"output_text": "Chính sách đổi trả cho phép...",
"message_id": "b0f16c77-a275-46c8-9dc8-8fe9fd5991cc",
"request_id": "req_01K..."
}Lưu conversation_id để tiếp tục hội thoại. Luôn gửi lại cùng external_user_id; người dùng khác không thể đọc hoặc tiếp tục hội thoại này.
4. Tích hợp qua backend
Route Handler dưới đây giữ API key ở server và lấy identity từ phiên đăng nhập của ứng dụng. Thay getAuthenticatedUserId() bằng hàm xác thực hiện có của bạn.
export async function POST(request: Request) {
const externalUserId = await getAuthenticatedUserId(request)
if (!externalUserId) {
return Response.json({ error: "Unauthorized" }, { status: 401 })
}
const { input, conversationId } = await request.json()
const response = await fetch(
`${process.env.ASSISTANT_API_URL}/v1/chat/responses`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ASSISTANT_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
external_user_id: externalUserId,
input,
conversation_id: conversationId,
stream: false,
}),
},
)
const data = await response.json()
return Response.json(data, {
status: response.status,
headers: {
"X-Request-ID": response.headers.get("X-Request-ID") ?? "",
},
})
}Không lấy external_user_id trực tiếp từ request body của browser. Giá trị này phải được backend suy ra từ user đã xác thực.
5. Tiếp tục hội thoại
Đổi idempotency key cho mỗi thao tác chat mới về mặt logic:
curl "$ASSISTANT_API_URL/v1/chat/responses" \
--request POST \
--header "Authorization: Bearer $ASSISTANT_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: $(uuidgen)" \
--data "{
\"external_user_id\": \"$EXTERNAL_USER_ID\",
\"conversation_id\": \"a12d5e41-7ab7-4c8f-b024-c2c38b5c43f4\",
\"input\": \"Chính sách có áp dụng cho sản phẩm giảm giá không?\",
\"stream\": false
}"Checklist trước production
- Lưu API key trong secret manager và chỉ cấp scope cần thiết.
- Dùng
external_user_idổn định, không chứa dữ liệu cá nhân hoặc secret. - Đặt timeout cho HTTP request; retry có giới hạn theo
retryablevàRetry-After. - Gửi một
Idempotency-Keymới cho mỗi thao tác chat logic và giữ nguyên key khi retry thao tác đó. - Lưu
X-Request-IDcùng status code để điều tra lỗi, nhưng không log API key hoặc nội dung nhạy cảm. - Dùng assistant và key riêng cho staging vì Preview chưa có sandbox tách biệt.
Tiếp theo
- Chat API: streaming, tệp, hội thoại và feedback.
- Voice API: voice client standard và realtime tự quản lý audio.
- Lỗi và giới hạn: retry, idempotency và rate-limit headers.
- API key và bảo mật: scopes, billing và quản lý key.