Cutin Image API v1 cutin.dev

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.

3 bước: gửi, hỏi, tải
# 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

Đị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ự.

Khóa chỉ hiện một lần khi được cấp. Hệ thống chỉ lưu bản băm, nên không thể xem lại. Mất khóa thì xin khóa mới và khóa cũ bị vô hiệu.

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

POST/v1/generateXếp một job vào hàng đợi. Trả về ngay.
TrườngKiểuMô tả
promptbắt buộcstringMô tả ảnh, tối đa 10.000 ký tự.
modestringHiện chỉ nhận text (mặc định).
aspect_ratiostring1:1 (mặc định), 4:3, 3:4, 3:2, 2:3, 16:9, 9:16
resolutionstring | số1024 (mặc định), 1536, 2048
stepssố20, 30 (mặc định), 40. Nhiều bước chậm hơn, chi tiết hơn.
seedsố nguyênBỏ trống để chọn ngẫu nhiên. Cùng seed và cùng tham số cho kết quả gần giống.
cfgbooleanBật true CFG.
negative_promptstringĐiều cần tránh, tối đa 10.000 ký tự.

Header

HeaderMô tả
Idempotency-KeyKhuyế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.
202 Accepted
{
  "job_id": "0b7e3c1a-5d1f-4c0e-9d0a-2f6a8b7c9e11",
  "status": "queued",
  "created_at": "2026-10-01T08:12:44.120Z"
}

Xem job

GET/v1/jobs/{job_id}Chỉ chủ khóa mới xem được job của mình.
200 OK khi job đã hoàn tất
{
  "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"
}
GET/v1/jobsLiệt kê job gần đây của khóa. Trả { jobs, count }.

Tải ảnh

GET/v1/jobs/{job_id}/imageTrả byte ảnh, không cần khóa.

Đị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ờ

queued→processing→completedhoặcfailed

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àoCách xử lý
400JSON 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.
401Thiếu hoặc sai khóa.Kiểm tra header xác thực.
413Nội dung yêu cầu lớn hơn 32 KB.Rút gọn prompt.
429Hế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.
503Toà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óa50
Job đang chạy cùng lúc, mỗi khóa3

Cần hạn mức cao hơn thì liên hệ để được cấp khóa riêng.