Tài liệu này là phần bổ sung của Điều khoản dịch vụ, dành riêng cho việc truy cập theo đường lập trình. Khi có khác biệt, Điều khoản dịch vụ là văn bản gốc.
1. Bề mặt API
TexAPI phơi ra các định dạng giao tiếp tương thích với ba chuẩn phổ biến trong ngành, để bạn dùng lại thư viện và công cụ sẵn có:
| Đường dẫn | Tương thích với | Hỗ trợ dòng |
|---|---|---|
POST /v1/chat/completions | OpenAI Chat Completions | Có |
POST /v1/responses | OpenAI Responses | Có |
POST /v1/messages | Anthropic Messages | Có |
POST /v1/images/generations | OpenAI Images (kèm /v1/images/edits) | Không |
GET /v1/models | OpenAI Models | — |
POST /v1beta/models/{model}:generateContent | Google Gemini | — |
POST /v1beta/models/{model}:streamGenerateContent | Google Gemini | Có |
POST /v1beta/models/{model}:countTokens | Google Gemini | — |
Tương thích không phải liên kết. Việc TexAPI nhận cùng hình dạng dữ liệu như OpenAI, Anthropic hay Google không có nghĩa TexAPI là các công ty đó, được các công ty đó uỷ quyền, hay liên kết với các công ty đó.
Chuyển đổi định dạng. Nếu mô hình bạn chọn không hỗ trợ định dạng bạn gửi, TexAPI tự chuyển đổi. Việc chuyển đổi có mất mát trong một số trường hợp — không phải mọi trường trong một định dạng đều có trường tương đương ở định dạng khác. Cụ thể, với yêu cầu Anthropic đã qua chuyển đổi, câu lệnh hệ thống của bạn có thể bị dời vị trí vào đầu tin nhắn người dùng đầu tiên; nội dung chỉ dẫn vẫn tới mô hình, nhưng vị trí thay đổi và điều đó có thể ảnh hưởng kết quả. Nếu bạn cần hành vi chính xác theo một định dạng, hãy chọn mô hình hỗ trợ sẵn định dạng đó.
2. Danh mục mô hình
Danh mục là động — được đồng bộ tự động từ nhà cung cấp hạ tầng khoảng mỗi 30 phút. Nghĩa là: mô hình mới có thể xuất hiện; mô hình có thể bị gỡ hoặc bị tắt mà TexAPI không được báo trước; giá có thể thay đổi.
Luôn lấy danh sách hiện hành từ GET /v1/models hoặc GET /api/models, không hard-code danh sách mô hình trong ứng dụng của bạn. Nếu bạn cần một mô hình cụ thể được bảo đảm khả dụng, đó là thoả thuận riêng — liên hệ hỗ trợ.
TexAPI không cam kết một mô hình cụ thể sẽ tồn tại trong tương lai, và không cam kết hành vi của một mô hình sẽ không đổi. Hai điều này nằm ngoài kiểm soát của TexAPI.
3. Xác thực
Dùng khoá API dạng sk-texapi-…, gửi qua header Authorization: Bearer … hoặc x-api-key: ….
Cách thứ ba được chấp nhận nhưng không khuyến nghị: tham số truy vấn ?key=…, tồn tại để tương thích với một số máy khách Gemini REST.
Quy tắc về khoá:
- Khoá thuộc về tổ chức của bạn, không thuộc về một cá nhân.
- Bản rõ của khoá chỉ hiển thị một lần khi tạo. TexAPI không lưu và không thể gửi lại. Mất khoá thì thu hồi và tạo mới.
- Bạn chịu trách nhiệm về mọi hoạt động dưới khoá của mình — kể cả khi khoá bị lộ do bạn. Nghi ngờ khoá bị lộ: thu hồi ngay tại Bảng điều khiển → Khoá API và thông báo cho hỗ trợ.
- Chia sẻ khoá cho bên thứ ba là bán lại dịch vụ và không được phép trừ khi có thoả thuận riêng bằng văn bản.
- Tạo khoá yêu cầu email đã xác minh.
TexAPI có thể thu hồi khoá không báo trước khi: tổ chức bị đình chỉ, phát hiện khoá bị lộ, hoặc có bằng chứng lạm dụng.
4. Hạn mức thông lượng
| Gói | Yêu cầu/phút | Token/phút | Số khoá API |
|---|---|---|---|
| Trả theo dùng | 60 | 250.000 | 2 |
| Dev | 300 | 1.000.000 | 5 |
| Studio | 800 | 4.000.000 | 20 |
| Scale | 2.000 | 12.000.000 | 100 |
Cách hạn mức hoạt động, nói chính xác:
- Yêu cầu/phút dùng cửa sổ cố định 60 giây. Biên giữa hai cửa sổ có thể cho phép lưu lượng cao gấp đôi trong thời gian rất ngắn — đây là đặc tính của cơ chế, không phải lỗi.
- Token/phút dùng token bucket, không phải cửa sổ cố định. Mỗi khoá có một xô chứa tối đa mức burst của gói (PAYG và Dev 1 triệu token, Studio 2 triệu, Scale 4 triệu) và nạp lại theo đúng tốc độ token/phút. Nhờ vậy một prompt lớn — ví dụ 900.000 token trên gói Dev — vẫn chạy được khi xô còn đủ token.
- Một yêu cầu lớn hơn cả burst bị từ chối bằng HTTP 400 với thông điệp nêu rõ giới hạn, không phải 429: chờ thêm không làm nó chạy được.
- Hạn mức đếm theo từng khoá API, không phải theo tổ chức.
- Token/phút đếm theo ước lượng token đầu vào cộng đầu ra tại thời điểm nhận yêu cầu, không phải theo số token thực tế sau khi trả lời. Phần đầu ra chỉ tính tối đa 4.096 token cho mục đích thông lượng.
- Vượt hạn mức trả HTTP 429 kèm thời gian chờ cần thiết. Hãy thử lại sau khoảng thời gian đó.
- Hạn mức là giới hạn trên, không phải năng lực được bảo đảm. Xem Mức độ dịch vụ mục 4.
Không được vượt hạn mức bằng cách: tạo nhiều tổ chức, tạo nhiều tài khoản, dùng nhiều khoá để chia lưu lượng nhằm nhân hạn mức, hay dùng proxy để phân tán.
5. Trần chi tiêu theo khoá
Bạn tự đặt trần chi tiêu theo tháng dương lịch cho từng khoá API. Đây là công cụ giới hạn thiệt hại quan trọng nhất bạn có, và TexAPI khuyến nghị dùng nó.
- Trần được kiểm tra trước khi gọi, dựa trên ước lượng chi phí. Vì chi phí thực có thể vượt ước lượng, trần có thể bị vượt một chút. Nó là biện pháp giới hạn, không phải một hàng rào tuyệt đối.
- Trần áp theo từng khoá, và không có trần ở cấp tổ chức. Một tổ chức có N khoá thì có N trần độc lập; giới hạn cuối cùng ở cấp tổ chức là số dư ví.
- Vượt trần trả HTTP 429 với mã lỗi riêng, không phải 402.
6. Cách tính token và cách tính tiền
Một lượt gọi có bốn loại token, bốn mức giá khác nhau:
| Loại | Nội dung | Mức giá |
|---|---|---|
| Input | phần bạn gửi lên | giá cơ sở |
| Output | phần mô hình sinh ra | thường 5–6 lần giá input |
| Cache read | phần đầu vào đã ghi nhớ từ lượt trước, đọc lại | thường 10% giá input |
| Cache write | lượt đầu ghi phần đó vào bộ đệm | 1,25 lần giá input |
Số token do nhà cung cấp hạ tầng báo về, không do TexAPI đếm. TexAPI dùng đúng con số đó để tính tiền. Khi hạ tầng không báo về — điển hình là khi dòng bị ngắt giữa đường — TexAPI dựng lại con số theo quy tắc công bố tại Số dư và tính tiền mục 5, và mỗi lượt gọi có biên nhận định giá ghi rõ nó đã dùng cơ sở nào.
Làm tròn trước bằng USD chuẩn: đến micro-đô (0,000001 USD), làm tròn lên. Phản hồi JSON không streaming sau tất toán giữ usage.cost_usd là khoản chuẩn đó và thêm usage.cost_credits, được suy ra sau tất toán theo tỷ lệ cố định trong texapi.credits_per_usd (hiện là 100). Một micro-đô bằng 0,0001 credit, nên mức làm tròn tối đa mỗi lượt gọi là 0,0001 credit.
7. Dòng (streaming)
- Bật bằng
stream: true, hoặc dùng:streamGenerateContentvới định dạng Gemini. - Định dạng Server-Sent Events, chuẩn theo định dạng bạn đang dùng.
- Chỉ những mô hình khai báo hỗ trợ dòng mới nhận
stream: true. - Các trường đã tất toán
cost_usd,cost_creditsvàcredits_per_usdhiện chỉ được thêm vào phản hồi JSON không streaming; hãy dùng mã lượt gọi và biên nhận định giá để đối chiếu lượt gọi streaming sau tất toán.
Điều quan trọng nhất về dòng, nói thẳng: nếu dòng bị ngắt giữa đường sau khi mô hình đã sinh ra một phần câu trả lời, phần đã gửi tới bạn có bị tính tiền — kể cả khi nguyên nhân ngắt là hết thời gian chờ ở phía hạ tầng, và kể cả khi chính bạn ngắt kết nối.
Lý do: mô hình đã thực hiện công việc và TexAPI đã trả tiền cho công việc đó. Giới hạn bảo vệ bạn: số tiền tính trong trường hợp này không vượt quá khoản đã tạm giữ khi bắt đầu lượt gọi. Nếu không có phần nào được gửi tới bạn, bạn không bị tính tiền.
8. Thời gian chờ, thử lại, chuyển tuyến
| Nội dung | Hành vi |
|---|---|
| Thời gian chờ lượt gọi thường | mặc định cấu hình ở mức 120 giây mỗi tuyến |
| Thời gian chờ với dòng | tính theo khoảng lặng giữa hai đoạn dữ liệu, đặt lại sau mỗi đoạn — nên câu trả lời dài không bị cắt oan |
| Thời gian chờ với tạo/sửa ảnh | dài hơn đáng kể |
| Chuyển tuyến khi lỗi | Có — TexAPI tự chuyển sang tuyến cung ứng khác của cùng mô hình |
| Trường hợp có chuyển tuyến | HTTP 429 từ hạ tầng, mọi lỗi 5xx, dòng rỗng, lỗi kết nối trước khi có phản hồi |
| Trường hợp không chuyển tuyến | hết thời gian chờ (vì việc sinh có thể đã chạy ở phía hạ tầng — gọi lại là tính tiền hai lần), và mọi lỗi 4xx khác |
Việc chuyển tuyến là trong suốt với bạn: bạn không biết và không cần biết lượt gọi được phục vụ bởi tuyến nào.
Nghĩa vụ của bạn về thử lại: dùng độ trễ tăng dần. Không thử lại ngay lập tức trong vòng lặp chặt — đó là hành vi bị xếp vào lạm dụng theo Chính sách sử dụng, và với lượt gọi hết thời gian chờ nó có thể làm bạn bị tính tiền hai lần cho cùng một công việc.
9. Bộ đệm câu lệnh
Với các mô hình hỗ trợ, phần đầu vào lặp lại giữa các lượt gọi có thể được ghi nhớ, và từ lượt sau chỉ tính khoảng 10% giá input. Cơ chế do hạ tầng và hãng mô hình quyết định, không do TexAPI.
Hệ quả: TexAPI không cam kết một phần đầu vào cụ thể sẽ được ghi nhớ, không cam kết thời gian giữ trong bộ đệm, và không cam kết mức tiết kiệm. Số token cache read/write thực tế xuất hiện trong biên nhận định giá của từng lượt gọi.
TexAPI không có bộ đệm phản hồi riêng. Cùng một câu hỏi gửi hai lần được gửi lên hạ tầng hai lần và tính tiền hai lần.
10. Nội dung yêu cầu của bạn
Nhắc lại vì đây là điểm dễ hiểu sai nhất:
- TexAPI không lưu nội dung câu hỏi và nội dung câu trả lời của bạn.
- TexAPI chuyển toàn bộ nội dung yêu cầu tới nhà cung cấp hạ tầng ngoài Việt Nam.
- TexAPI quét nội dung do bạn viết bằng bộ lọc từ khoá chạy cục bộ; khi một yêu cầu bị chặn, một đoạn trích tối đa 500 ký tự được lưu làm bằng chứng.
- TexAPI không chuyển tiếp địa chỉ IP của bạn và không gắn định danh khách hàng khi gọi hạ tầng.
11. Thay đổi API
| Loại thay đổi | Thông báo trước |
|---|---|
| Thêm trường, thêm endpoint, thêm mô hình (tương thích ngược) | không cần |
| Thay đổi phá vỡ tương thích trên endpoint đang có | 90 ngày |
| Ngừng một endpoint | 90 ngày |
| Gỡ một mô hình vì hạ tầng ngừng cung cấp | ngay khi TexAPI biết — có thể không có thông báo trước, do nằm ngoài kiểm soát |
| Thay đổi hạn mức theo gói (giảm) | 30 ngày |
| Thay đổi giá | xem Số dư và tính tiền mục 7 |
| Xử lý khẩn cấp về bảo mật | ngay lập tức, có thể sau khi đã thực hiện |
Thay đổi được công bố qua kênh thông báo trong sản phẩm và email tới địa chỉ tài khoản.
12. Nội dung không được gửi qua API
Tóm tắt; đầy đủ ở Chính sách sử dụng.
Không gửi qua TexAPI: nội dung nhằm mục đích phạm pháp; nội dung xâm hại trẻ em; hướng dẫn chế tạo vũ khí hoặc chất nguy hiểm; mã độc; nội dung nhằm gian lận, lừa đảo, giả mạo danh tính người khác; nội dung xâm phạm quyền sở hữu trí tuệ; dữ liệu cá nhân của người khác mà bạn không có cơ sở pháp lý để xử lý.
Không gửi qua TexAPI, vì lý do bảo vệ dữ liệu chứ không phải vì bị cấm: dữ liệu cá nhân nhạy cảm, dữ liệu sức khoẻ, dữ liệu sinh trắc học, thông tin tài khoản thanh toán, dữ liệu bạn có nghĩa vụ pháp lý không được chuyển ra nước ngoài.
Nếu ứng dụng của bạn hiển thị kết quả AI cho người dùng cuối, bạn phải cho họ biết đó là nội dung do AI tạo ra.
13. Giới hạn của kết quả AI
Kết quả do mô hình sinh ra có thể sai, thiếu, lỗi thời hoặc gây nhầm lẫn, kể cả khi diễn đạt rất tự tin. Đây là đặc tính của công nghệ, không phải khiếm khuyết của TexAPI hay của mô hình cụ thể.
Nghĩa vụ của bạn: không dùng kết quả làm cơ sở duy nhất cho quyết định ảnh hưởng tới quyền, sức khoẻ, tài chính, việc làm, chỗ ở, giáo dục hay tình trạng pháp lý của một người, mà không có người có chuyên môn xem xét trước. Với các lĩnh vực này, điều khoản của nhà cung cấp hạ tầng buộc phải có người xem xét và phải công bố việc dùng AI ở đầu mỗi phiên làm việc. Nghĩa vụ đó chảy xuống bạn qua Điều khoản dịch vụ.
14. Tài liệu kỹ thuật
Đặc tả OpenAPI: GET /openapi.json, GET /openapi.yaml. Đặc tả là tài liệu kỹ thuật, không phải cam kết hợp đồng; khi có khác biệt, tài liệu này và Điều khoản dịch vụ là văn bản gốc.