Hướng dẫnAPI cho Developer
Developer15 phút
API cho Developer
Tích hợp AI generation vào app của bạn qua REST API. Từ tạo key đến deploy production.
Quick Start
Tạo API key
1. Vào trang API (menu "API")
2. Click "Tạo API Key"
3. Đặt tên key (ví dụ: "my-app-prod")
4. Copy key ngay — key chỉ hiện 1 lần
Key có dạng:
sk_live_...Tip: Tạo key riêng cho mỗi môi trường (dev/staging/prod) để dễ quản lý và revoke.
Test nhanh với curl
```bash
curl -X POST https://tramsangtao.com/v1/image/generate \
-H "Authorization: Bearer sk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2-pro",
"prompt": "A cute cat wearing sunglasses",
"aspect_ratio": "1:1"
}'
`
Response trả về job_id → poll status để lấy kết quả.Poll job status
```bash
curl https://tramsangtao.com/v1/jobs/JOB_ID \
-H "Authorization: Bearer sk_live_YOUR_KEY"
`
Status flow: pending → processing → completed (có result_url) hoặc failed.
Poll mỗi 3-5 giây. Timeout sau 5 phút cho image, 10 phút cho video.Endpoints chính
Image generation
POST /v1/image/generate
Params:
- model (required): flux-2-pro, chatgpt-image, seedream-4.5, nano-banana...
- prompt (required): mô tả ảnh
- image_url (optional): URL ảnh gốc cho I2I
- aspect_ratio (optional): 1:1, 16:9, 9:16, 4:3, 3:4
- speed (optional): normal, fast, highVideo generation
POST /v1/video/generate
Params:
- model (required): kling-2.6, kling-3.0, veo3.1-fast...
- prompt (required): mô tả video + chuyển động
- image_url (optional): ảnh gốc cho I2V
- duration (optional): 5, 10 (giây)
- aspect_ratio (optional): 16:9, 9:16, 1:1Check balance & limits
GET /v1/balance — xem credits còn lại
GET /v1/limits — xem concurrent job limits
GET /v1/models — danh sách models + giá creditsBest practices
Error handling
Luôn handle các case:
-
401 — key không hợp lệ
- 402 — hết credits
- 429 — rate limit (đợi rồi retry)
- 500 — server error (retry 1-2 lần)
Khi job failed, check field error trong response để biết lý do.Webhook vs Polling
Hiện tại API dùng polling. Recommend:
1. Poll mỗi 3s cho image, 5s cho video
2. Set timeout (5 phút image, 10 phút video)
3. Dùng exponential backoff nếu server busy
Tip: Đừng poll quá nhanh (< 1s) — sẽ bị rate limit.
Credit management
- Check
/v1/balance trước khi generate để tránh 402
- Dùng /v1/models để biết giá mỗi model trước
- Set alert khi balance thấp
- Dùng model rẻ (nano-banana) cho testing, model xịn cho production