Tạo ảnh với ThAPI API

Kết nối API

Gửi yêu cầu đến URL API của site với Content-Type: application/json và Authorization: Bearer YOUR_API_KEY. Bạn cũng có thể dùng x-api-key.

Giữ API key ở phía máy chủ. Các ví dụ dùng biến môi trường và chưa gửi yêu cầu thay bạn.

read -r -s -p "STALI_API_KEY: " STALI_API_KEY
export STALI_API_KEY
printf '\n'
curl -fsS https://thapi.cloud/v1/models -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}"

Chọn model tạo ảnh

Dùng req/gpt-image-2 hoặc req/gemini-3.0-pro-image. Nếu bỏ model hoặc gửi giá trị trống, hai endpoint ảnh mặc định dùng req/gpt-image-2.

Gọi GET /v1/models để xem model và pricing.per_request hiện tại. API key cần được cấp quyền sử dụng model đã chọn.

Tạo ảnh từ mô tả

Gửi POST /v1/images/generations với model và prompt mô tả ảnh. Ví dụ bắt đầu với n: 1 và size: 1024x1024. Endpoint trả JSON sau khi xử lý xong. stream bị đặt thành false; endpoint này không trả luồng SSE.

Ví dụ cURL dùng Bash trên macOS, Linux hoặc WSL. Với Python, cài thư viện bằng pip install requests. Với Node.js, dùng phiên bản 18 trở lên, lưu mã thành tệp .mjs và dùng fetch có sẵn.

curl --fail-with-body --dump-header image-response-headers.txt "https://thapi.cloud/v1/images/generations" \
  -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "req/gpt-image-2",
  "prompt": "A small botanical robot tending a seedling, studio product photography, soft natural light, clean ivory background, no text",
  "n": 1,
  "size": "1024x1024"
}'

Chỉnh sửa theo ảnh tham chiếu

Gửi POST /v1/images/edits bằng JSON, gồm prompt không rỗng và image. Ảnh có thể là data URL, chuỗi base64 hoặc URL http(s) công khai. Với cURL, thay https://example.com/reference.png bằng URL ảnh công khai thực tế của bạn. Với Python hoặc Node.js, đặt reference.png cùng thư mục chạy ví dụ.

Ngoài image, có thể dùng image_url, reference_image, ref_image hoặc refImage. Giá trị có thể là chuỗi hoặc đối tượng {url: ...}; nên gửi một trường ảnh duy nhất. Endpoint chỉnh sửa nhận JSON, không nhận multipart/form-data. URL ảnh phải truy cập công khai và không chứa thông tin đăng nhập; địa chỉ nội bộ bị chặn. Ảnh tham chiếu hỗ trợ PNG, JPEG, WebP và GIF. Không dùng trực tiếp images.edit của SDK nếu SDK gửi multipart/form-data. Endpoint này yêu cầu JSON; các ví dụ Python requests và Node.js fetch minh họa đúng định dạng.

curl --fail-with-body --dump-header image-response-headers.txt "https://thapi.cloud/v1/images/edits" \
  -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "req/gpt-image-2",
  "prompt": "Keep the subject and composition, change the background to a warm ivory studio",
  "image": "https://example.com/reference.png",
  "n": 1,
  "size": "1024x1024"
}'

Tham số và giới hạn

Toàn bộ JSON yêu cầu tối đa 20 MiB, gồm dữ liệu ảnh đã mã hóa. Base64 làm tăng kích thước dữ liệu. Giới hạn của Playground là riêng biệt.

Đọc và lưu ảnh trả về

Đọc mảng data trong phản hồi JSON. Tùy nhà cung cấp, ảnh nằm ở b64_json, b64Json hoặc url. Các trường bổ sung có thể khác nhau giữa các model.

{
  "data": [
    {
      "b64_json": "<base64 image bytes>"
    }
  ]
}

Nếu nhận base64, giải mã thành tệp ảnh hoặc tạo data URL với MIME type phù hợp định dạng thực tế. Không mặc định mọi kết quả đều là PNG. Nếu nhận URL, dùng URL để tải hoặc hiển thị ảnh. Thời gian tồn tại và quyền truy cập URL phụ thuộc nhà cung cấp.

Lưu x-thapi-request-id để tra cứu; xem x-thapi-model, x-thapi-price-vnd-per-request và x-thapi-cost-vnd trong header phản hồi thành công.

Chi phí theo lượt gọi

Model ảnh được tính theo request. Kiểm tra pricing.per_request trong GET /v1/models trước khi chạy; số dư hoặc hạn mức của API key có thể chặn yêu cầu. Token trong phản hồi hoặc header không phải cơ sở để tự tính lại giá model ảnh. Yêu cầu mới có thể phát sinh lượt tính phí mới.

Không tự động gửi lại khi timeout hoặc mất kết nối: yêu cầu trước có thể đã được xử lý. Kiểm tra lịch sử Usage và lưu request ID để đối chiếu hoặc cung cấp khi cần hỗ trợ trước khi quyết định gọi lại.

Xử lý lỗi có kiểm soát

Lỗi gateway có dạng {type: "error", error: {type, message, ...}}. Đọc HTTP status và error.message, đồng thời lưu request ID nếu có.

Trước khi gửi yêu cầu

Kiểm tra API key, quyền model và giá hiện tại. Gửi JSON đúng endpoint, giữ yêu cầu nhỏ và dùng một ảnh cho ví dụ đầu tiên. Chuẩn bị xử lý cả base64 lẫn URL, lưu request ID và kiểm tra kết quả trước khi gọi lại.

1. Kiểm tra API key và quyền model.
2. Đối chiếu model và giá trong /v1/models.
3. Kiểm tra JSON, prompt và dữ liệu ảnh.
4. Xử lý cả base64 và URL.
5. Kiểm tra lịch sử Usage; lưu request ID để đối chiếu hoặc liên hệ hỗ trợ.