API Dành cho lập trình viên

Công cụ ảnh AI
gọi thẳng từ code.

Tám công cụ AI chuyên dụng của tiệm — xóa nền, tăng độ phân giải, khôi phục màu, chỉnh sửa theo yêu cầu, thay trang phục, xóa vật thể, mở rộng ảnh và thay khuôn mặt — dùng được từ máy chủ, ứng dụng hay script của bạn. Một khóa API, trừ Xu đúng như khi bấm trên web, từ 1 Xu mỗi ảnh. Job hỏng thì Xu tự về ví.

Khóa API

Khóa đại diện cho chính tài khoản của bạn: mỗi lượt gọi trừ Xu trong ví của bạn. Giữ khóa ở phía máy chủ — đừng nhúng vào ứng dụng hay trang web mà người khác xem được mã nguồn.

Cần bậc Bạc trở lên

API mở cho tài khoản đã nạp tổng 500 Xu trở lên — xem bảng bậc. Bậc tính theo tổng đã nạp từ trước tới nay, không phải số dư hiện tại.

Đang tải…

Khóa mới của bạn — chép lại ngay

Tiệm chỉ lưu bản băm, nên khóa này không xem lại được sau khi bạn rời trang. Mất thì thu hồi rồi tạo khóa khác.

Thử ngay trên trang

Chạy thật vào đúng endpoint POST ở trên bằng khóa của bạn — không phải bản mô phỏng. Mỗi lượt bấm trừ Xu thật đúng như khi gọi từ code.

Công cụ

Khóa API

Ảnh gốc Kéo thả hoặc bấm chọn · JPG/PNG/WEBP ≤ 20 MiB Ảnh thứ hai Kéo thả hoặc bấm chọn

Tham số

Lưu kết quả vào Tác vụ

Ảnh kết quả Mở ảnh gốc ↗

Chưa có

Phản hồi JSON

Ví dụ code

Một lượt chạy gồm hai bước: tạo job rồi hỏi kết quả. Tạo job trả về ngay id và poll_url; ảnh xong sau vài giây thì status đổi thành success và có output_url.

Mã dưới đây bám theo lựa chọn ở khu Thử ngay — đổi công cụ, tham số hay khóa ở trên là mã tự viết lại.

Gửi lại an toàn

Kèm header Idempotency-Key (một chuỗi bạn tự đặt cho mỗi ảnh) thì mạng lỗi gọi lại bao nhiêu lần cũng chỉ tạo một job và trừ Xu một lần — lần sau trả về đúng job cũ.

Công cụ và tham số

Giá dưới đây là giá thật đang áp dụng, đọc từ cùng một bảng với trang công cụ. Bậc của bạn được bớt Xu ở đây y như khi bấm trên web — job tạo qua API đi đúng một đường trừ ví, xem bảng bậc; đăng nhập rồi thì giá bên dưới hiện đúng số ví bị trừ. Mọi tham số đều tùy chọn trừ khi ghi bắt buộc; gửi tên tham số lạ thì API báo lỗi ngay thay vì im lặng chạy sai.

Xóa nền ảnh tool = remove-bg

3 Xu / ảnh

Tách chủ thể khỏi nền bằng BiRefNet. Mặc định trả PNG nền trong suốt. Bản có giao diện: /xoa-nen.

Gửi tới POST /api/v1-jobs-create.php với tool=remove-bg và một ảnh image.

Tham số	Giá trị	Mặc định	Ghi chú
`model`	general · general-hr · general-lite · general-lite-2k · portrait · matting …tổng 8 giá trị, xem `GET /v1/tools`	general	general đa dụng, matting cho tóc/lông, portrait cho người, dynamic cho sản phẩm.
`background`	chuỗi	(trống)	Mã màu nền dạng #RRGGBB. Bỏ trống = nền trong suốt.
`output_format`	png · jpg · webp	png	JPG không giữ được nền trong suốt nên sẽ tự đổi về PNG khi không đặt background.

Tăng độ phân giải tool = upscale

5 Xu / ảnh

Phóng to ảnh và tái tạo chi tiết. Trần ảnh đầu vào thay đổi theo model (2,5–25 MP). Bản có giao diện: /tang-do-phan-giai.

Gửi tới POST /api/v1-jobs-create.php với tool=upscale và một ảnh image.

Tham số	Giá trị	Mặc định	Ghi chú
`scale`	số, 1–8	2	Số lần phóng to.
`model`	4x-UltraSharp · ESRGAN_4x · R-ESRGAN General 4xV3 · R-ESRGAN General WDN 4xV3 · R-ESRGAN AnimeVideo · R-ESRGAN 4x+ …tổng 32 giá trị, xem `GET /v1/tools`	4x-UltraSharp	Tên model làm nét. Anime dùng "R-ESRGAN 4x+ Anime6B", ảnh người dùng "4xFaceUpDAT".
`output_format`	jpg · png · webp	jpg	WebP giới hạn mỗi cạnh 16383px sau khi phóng.

Khôi phục màu ảnh tool = khoi-phuc-mau

1 Xu / ảnh

Tô màu ảnh đen trắng bằng DDColor, giữ nguyên kích thước ảnh gốc. Bản có giao diện: /khoi-phuc-mau-anh.

Gửi tới POST /api/v1-jobs-create.php với tool=khoi-phuc-mau và một ảnh image.

Tham số	Giá trị	Mặc định	Ghi chú
`style`	natural · artistic	natural	natural bám màu thật, artistic rực hơn.
`saturation`	số, 0.3–2	1	Độ đậm màu.
`sharpen`	true · false	false	Làm nét ×2 sau khi tô màu. CÓ PHỤ PHÍ +1 Xu và siết ảnh vào còn 12MP.
`output_format`	jpg · png · webp	jpg

Chỉnh sửa theo yêu cầu tool = chinh-sua-anh-ai

10 Xu / ảnh

Mô tả bằng tiếng Việt muốn sửa gì, model sửa đúng chỗ đó và giữ nguyên phần còn lại. Bản có giao diện: /chinh-sua-anh-ai.

Gửi tới POST /api/v1-jobs-create.php với tool=chinh-sua-anh-ai và một ảnh image.

Tham số	Giá trị	Mặc định	Ghi chú
`request`	chuỗi, tối đa 600 ký tự	bắt buộc	Câu yêu cầu, tối thiểu 3 ký tự. Ví dụ: "đổi áo sang màu trắng, giữ nguyên khuôn mặt".
`size`	auto · 1:1 · 2:3 · 3:2 · 3:4 · 4:3 …tổng 8 giá trị, xem `GET /v1/tools`	auto	Tỉ lệ khung ảnh ra. auto giữ tỉ lệ ảnh vào; chọn tỉ lệ khác thì model dựng lại bố cục.

Làm nét ảnh chân dung tool = lam-net-anh

5 Xu / ảnh

Phục hồi và làm nét khuôn mặt trong ảnh mờ, ảnh cũ. Ảnh ra gấp đôi kích thước. Trần ảnh vào 6 MP. Bản có giao diện: /lam-net-anh.

Gửi tới POST /api/v1-jobs-create.php với tool=lam-net-anh và một ảnh image.

Tham số	Giá trị	Mặc định	Ghi chú
`model`	Phục hồi chân dung v1 · Phục hồi chân dung v2	Phục hồi chân dung v1	v1 (mặc định) chạy trên máy của tiệm, giữ nét ảnh gốc sát hơn; v2 phục hồi khuôn mặt tự nhiên hơn.
`output_format`	jpg · png · webp	jpg

Thay trang phục tool = thay-doi-trang-phuc

5 Xu / ảnh

Mặc bộ đồ ở ảnh trang phục lên người trong ảnh gốc. Ảnh trang phục nên là ảnh MỘT món đồ, tốt nhất là ảnh sản phẩm nền trắng. Bản có giao diện: /thay-doi-trang-phuc.

Gửi tới POST /api/v1-jobs-create.php với tool=thay-doi-trang-phuc và một ảnh image.

Tham số	Giá trị	Mặc định	Ghi chú
`category`	auto · upper_body · lower_body · dresses	auto	Loại trang phục. auto để máy tự đoán; đặt tay khi ảnh đồ dễ nhầm (vd váy liền vs áo).
`garment_text`	chuỗi, tối đa 120 ký tự	(trống)	Mô tả thêm về món đồ (màu, chất liệu, kiểu tay áo…) khi ảnh trang phục chưa rõ.

Xóa vật thể thừa tool = xoa-vat-the

1 Xu / ảnh

Gửi ẢNH GỐC + MẶT NẠ cùng kích thước. Vùng TRẮNG trên mặt nạ là phần bị xóa và vẽ lại theo nền xung quanh; vùng ĐEN giữ nguyên. Bản có giao diện: /xoa-vat-the.

Endpoint riêng: POST https://tiemanhai.com/api/v1-xoa-vat-the.php — gửi hai ảnh: image</code> + <code>mask. Trả về job giống hệt, poll bằng cùng một endpoint.

Tham số	Giá trị	Mặc định	Ghi chú
`mode`	simple · smart	simple	simple (LaMa) nhanh và rẻ, hợp vật thể nhỏ. smart (SDXL) vẽ lại nền phức tạp, GIÁ RIÊNG 3 Xu/lượt và chạy nền — poll như job thường.
`mask_expand`	số, 0–128	8	Nới rộng mặt nạ thêm bao nhiêu pixel trước khi xóa — thiếu viền thì còn bóng vật thể.
`mask_blur`	số, 0–64	4	Làm mềm mép mặt nạ để mối nối đỡ lộ.
`output_format`	jpg · png · webp	jpg

Mở rộng ảnh tool = mo-rong-anh

5 Xu / ảnh

Gửi ẢNH ĐÃ ĐẶT TRONG KHUNG MỚI (phần thừa để trống) + MẶT NẠ cùng kích thước. Vùng TRẮNG là phần trống cần AI vẽ thêm. Bản có giao diện: /mo-rong-anh.

Endpoint riêng: POST https://tiemanhai.com/api/v1-mo-rong-anh.php — gửi hai ảnh: image</code> + <code>mask. Trả về job giống hệt, poll bằng cùng một endpoint.

Tham số	Giá trị	Mặc định	Ghi chú
`prompt`	chuỗi, tối đa 500 ký tự	(trống)	Mô tả cảnh muốn vẽ thêm. Bỏ trống thì dùng prompt nền mặc định của tiệm.
`mask_expand`	số, 0–128	12
`mask_blur`	số, 0–64	6
`steps`	số, 1–16	8	Số bước khuếch tán. Cao hơn thì kỹ hơn nhưng chậm hơn.
`seed`	số, -1–2147483647	-1	-1 = ngẫu nhiên. Đặt số cố định để chạy lại ra đúng kết quả cũ.
`output_format`	jpg · png · webp	jpg

Thay khuôn mặt tool = thay-doi-khuon-mat

1 Xu / ảnh

Gửi ẢNH ĐÍCH + ẢNH KHUÔN MẶT MỚI. Mặc định thay mọi khuôn mặt nhìn thấy trong ảnh đích. Giá tính theo SỐ MẶT thật sự được thay. Bản có giao diện: /thay-doi-khuon-mat.

Endpoint riêng: POST https://tiemanhai.com/api/v1-thay-doi-khuon-mat.php — gửi hai ảnh: image</code> + <code>face. Trả về job giống hệt, poll bằng cùng một endpoint.

Tham số	Giá trị	Mặc định	Ghi chú
`swap_all`	true · false	true	Thay mọi khuôn mặt. Đặt false kèm target_index để chỉ thay đúng một mặt.
`target_index`	số, 0–19	0	Mặt thứ mấy trong ảnh đích (đếm từ 0, trái sang phải). Chỉ có tác dụng khi swap_all=false.
`enhancer`	true · false	true	Làm nét khuôn mặt sau khi ghép, MẶC ĐỊNH BẬT. CÓ PHỤ PHÍ +2 Xu mỗi lượt — đặt false nếu không cần.
`ai_label`	true · false	true	Đóng nhãn "Tạo bởi AI" vào góc ảnh. Tắt là bạn tự chịu trách nhiệm về ảnh tạo ra.
`output_format`	jpg · png · webp	jpg

Endpoint

Xác thực bằng header Authorization: Bearer <khóa> (hoặc X-Api-Key nếu hạ tầng của bạn nuốt mất header Authorization). Mọi phản hồi đều là JSON có trường ok.

Endpoint	Việc
POST `https://tiemanhai.com/api/v1-jobs-create.php`	Tạo một lượt chạy. Gửi `tool`, ảnh (`image` multipart hoặc `image_url` / `image_base64` trong JSON) và `params`. Trừ Xu ở bước này.
GET `https://tiemanhai.com/api/v1-jobs-get.php?id={id}`	Hỏi trạng thái. Xong thì có `output_url`. Hỏi lại mỗi 2 giây là hợp lý.
`params.save_to_tasks`	Tham số CHUNG cho mọi công cụ, mặc định `true`. Đặt `false` thì lượt chạy không hiện ở Tác vụ — ảnh vẫn trả về bình thường và Xu vẫn trừ như thường.
GET `https://tiemanhai.com/api/v1-tools.php`	Danh mục công cụ + giá Xu hiện hành + đặc tả tham số. Không cần khóa. Đọc từ đây thay vì chép cứng bảng giá vào code. Gửi kèm khóa thì mỗi mục có thêm `your_price_xu` — số Xu ví bạn thật sự bị trừ sau khi bớt theo bậc — và `tier_discount_xu`; `price_xu` vẫn là giá niêm yết. Khóa sai thì endpoint này lờ đi chứ không báo lỗi.
GET `https://tiemanhai.com/api/v1-usage.php`	Số dư Xu + thống kê lượt gọi. Nhận `?days=` từ 1 đến 90.

Trạng thái của một job

`pending`	Đã vào hàng đợi, chưa tới lượt chạy.
`processing`	Máy đang chạy.
`success`	Xong — lấy ảnh ở `output_url`.
`failed` `timeout` `cancelled` `refunded`	Hỏng. Xu đã được hoàn tự động (`refunded: true`), lý do ở `error`.

Mã lỗi

Mọi lỗi đều trả JSON {"ok":false,"error":{"code":"…","message":"…"}}. Bắt theo code chứ đừng bắt theo message — câu chữ có thể đổi.

Mã lỗi	Nghĩa
`api_key_missing` · `api_key_invalid`	401 — thiếu khóa hoặc khóa đã thu hồi.
`insufficient_balance`	402 — hết Xu. Nạp thêm rồi gọi lại.
`tool_not_in_api`	403 — công cụ chưa mở qua API.
`param_unknown` · `param_invalid` · `param_required`	422 — sai tên hoặc sai giá trị tham số. Thông báo có ghi rõ tên đúng.
`image_required` · `file_format_invalid` · `image_too_large`	422 — ảnh thiếu, sai định dạng (chỉ JPG/PNG/WEBP), hoặc quá 20 MiB / 40 megapixel.
`rate_limited`	429 — gọi quá nhanh. Chờ một nhịp rồi thử lại.
`tool_maintenance`	503 — công cụ đang bảo trì.

Mức dùng

Chỉ tính những lượt chạy sinh ra từ khóa API — lượt bấm trên web không lẫn vào đây. Số Xu đã tiêu không tính các job hỏng đã hoàn.

Đang tải…

—Xu còn lại

—Lượt gọi 30 ngày

—Thành công

—Xu đã tiêu

Công cụ ảnh AIgọi thẳng từ code.

Khóa API

Thử ngay trên trang

Ví dụ code

Công cụ và tham số

Endpoint

Mã lỗi

Mức dùng

Công cụ ảnh AI
gọi thẳng từ code.