Tạo ảnh bằng một lệnh HTTP.
Gửi mô tả, nhận lại job_id, hỏi trạng thái, tải ảnh PNG. Chạy bất đồng bộ trên GPU, trả tiền theo lượt dùng.
Một ảnh 1024² mất khoảng 12 giây khi GPU đã nóng, và khoảng 90 giây nếu phải khởi động lại. Mỗi khóa tạo tối đa 50 ảnh mỗi ngày và chạy 3 job cùng lúc.
# 1. Gửi job curl -X POST $BASE/v1/generate \ -H "Authorization: Bearer $CUTIN_KEY" \ -H "Idempotency-Key: don-hang-1042" \ -H "Content-Type: application/json" \ -d '{"prompt":"Quả táo đỏ trên mặt đá cẩm thạch, ánh sáng studio"}' # 2. Hỏi trạng thái (lặp mỗi 3-5 giây) curl $BASE/v1/jobs/$JOB_ID -H "Authorization: Bearer $CUTIN_KEY" # 3. Tải ảnh khi status = completed curl $BASE/v1/jobs/$JOB_ID/image -o anh.png
const H = { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" }; const { job_id } = await (await fetch(`${BASE}/v1/generate`, { method: "POST", headers: { ...H, "Idempotency-Key": "don-hang-1042" }, body: JSON.stringify({ prompt: "Quả táo đỏ trên mặt đá cẩm thạch" }), })).json(); let job; do { await new Promise(r => setTimeout(r, 4000)); job = await (await fetch(`${BASE}/v1/jobs/${job_id}`, { headers: H })).json(); } while (job.status === "queued" || job.status === "processing"); // job.result_url dùng được ngay, không cần khóa
import os, time, requests BASE, H = os.environ["BASE"], {"Authorization": f"Bearer {os.environ['CUTIN_KEY']}"} job_id = requests.post(f"{BASE}/v1/generate", headers={**H, "Idempotency-Key": "don-hang-1042"}, json={"prompt": "Quả táo đỏ trên mặt đá cẩm thạch"}).json()["job_id"] while True: job = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=H).json() if job["status"] in ("completed", "failed"): break time.sleep(4) open("anh.png", "wb").write(requests.get(job["result_url"]).content)
Địa chỉ API: https://ai.cutin.dev.
Xác thực
Mỗi yêu cầu cần một khóa API. Gửi trong header Authorization: Bearer <khóa> hoặc X-API-Key: <khóa>. Khóa có dạng cutin_ theo sau 48 ký tự.
Thiếu khóa, khóa sai hoặc khóa bị khóa đều trả 401 Unauthorized. Không có chế độ bỏ qua xác thực.
Tạo ảnh
| Trường | Kiểu | Mô tả |
|---|---|---|
| promptbắt buộc | string | Mô tả ảnh, tối đa 10.000 ký tự. |
| mode | string | Hiện chỉ nhận text (mặc định). |
| aspect_ratio | string | 1:1 (mặc định), 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 |
| resolution | string | số | 1024 (mặc định), 1536, 2048 |
| steps | số | 20, 30 (mặc định), 40. Nhiều bước chậm hơn, chi tiết hơn. |
| seed | số nguyên | Bỏ trống để chọn ngẫu nhiên. Cùng seed và cùng tham số cho kết quả gần giống. |
| cfg | boolean | Bật true CFG. |
| negative_prompt | string | Điều cần tránh, tối đa 10.000 ký tự. |
Header
| Header | Mô tả |
|---|---|
| Idempotency-Key | Khuyến nghị. 1-128 ký tự A-Za-z0-9_.:-. Gửi lại cùng giá trị sẽ nhận lại job cũ (200, idempotent_replay: true) thay vì tạo job mới và tính thêm lượt. |
{
"job_id": "0b7e3c1a-5d1f-4c0e-9d0a-2f6a8b7c9e11",
"status": "queued",
"created_at": "2026-10-01T08:12:44.120Z"
}
Xem job
{
"job_id": "0b7e3c1a-5d1f-4c0e-9d0a-2f6a8b7c9e11",
"status": "completed",
"prompt": "Quả táo đỏ trên mặt đá cẩm thạch, ánh sáng studio",
"mode": "text",
"aspect_ratio": "1:1",
"resolution": "1024",
"steps": 20,
"seed": 482913,
"width": 1024,
"height": 1024,
"result_url": "https://ai.cutin.dev/v1/jobs/0b7e…/image",
"error": null,
"created_at": "2026-10-01T08:12:44.120Z",
"started_at": "2026-10-01T08:12:46.003Z",
"completed_at": "2026-10-01T08:12:59.410Z"
}
{ jobs, count }.Tải ảnh
Địa chỉ ảnh dựa trên job_id ngẫu nhiên nên đủ để nhúng vào <img> hoặc chia sẻ. Ai có đường dẫn đều xem được, vì vậy đừng đăng job_id của ảnh riêng tư. Trước khi job hoàn tất, đường dẫn trả 404.
Trạng thái và thời gian chờ
Job nằm ở queued cho đến khi có GPU rảnh. Khi hệ thống không có worker nóng, lần gọi đầu mất khoảng 90 giây để tải mô hình. Các lần sau thường dưới 15 giây. Hỏi trạng thái mỗi 3-5 giây là đủ; hỏi dày hơn không làm job nhanh hơn.
Job quá hạn chạy (10 phút) chuyển sang failed và trường error nêu lý do. Lượt dùng của job lỗi vẫn được tính trong hạn mức ngày.
Hạn mức và mã lỗi
Mọi lỗi đều có dạng { "error": "…" }. Với 429 và 503, đợi đúng số giây trong header Retry-After rồi gửi lại.
| Mã | Khi nào | Cách xử lý |
|---|---|---|
| 400 | JSON sai, thiếu prompt, giá trị ngoài danh sách cho phép, Idempotency-Key sai định dạng. | Sửa yêu cầu theo thông điệp lỗi. Không gửi lại nguyên văn. |
| 401 | Thiếu hoặc sai khóa. | Kiểm tra header xác thực. |
| 413 | Nội dung yêu cầu lớn hơn 32 KB. | Rút gọn prompt. |
| 429 | Hết hạn mức ngày (Retry-After: 3600) hoặc quá số job đang chạy (Retry-After: 10). | Đợi rồi thử lại. Dùng Idempotency-Key để không tạo trùng. |
| 503 | Toàn hệ thống đầy (Retry-After: 30). | Thử lại sau vài giây. |
| Hạn mức (mặc định) | Giá trị |
|---|---|
| Job mỗi 24 giờ, mỗi khóa | 50 |
| Job đang chạy cùng lúc, mỗi khóa | 3 |
Cần hạn mức cao hơn thì liên hệ để được cấp khóa riêng.