Tổng Quan
Tạo một hình ảnh đã chỉnh sửa hoặc mở rộng dựa trên ảnh gốc và prompt. Route này hỗ trợ cả:- luồng upload
multipart/form-datatương thích OpenAI được mô tả bên dưới - request JSON cung cấp
image_url,image_urls, hoặc tham chiếu chính thứcimagescho các nhóm image-to-image được hỗ trợ
gpt-image-2 được hỗ trợ tại đây. Endpoint chấp nhận upload multipart image, JSON image_url / image_urls, và tham chiếu chính thức images[] (image_url hoặc file_id) với tối đa 16 ảnh nguồn. Hãy tạo file_id qua /v1/files trước. Đặt async: true để nhận task trước; các model edit FLUX/BFL chính thức cũng dùng cùng luồng polling task.Edit bằng gpt-image-2 không chấp nhận resolution hoặc background; hãy dùng size cho kích thước đầu ra. Với edit nhiều ảnh hoặc độ trễ cao, nên đặt async: true rồi polling task được trả về.Request Nano Banana dùng ảnh tham chiếu (nano-banana, nano-banana-2, và nano-banana-pro) được cung cấp qua /v1/images/generations với operation: "image-to-image" và image_urls, không phải endpoint /v1/images/edits này.Các model chỉnh sửa ảnh xAI Grok Imagine (grok-imagine-image, grok-imagine-image-quality, và legacy grok-imagine-image-pro) chấp nhận tối đa 3 ảnh nguồn. Request có hơn 3 ảnh nguồn sẽ thất bại ở bước kiểm tra input với 400 too_many_images.input_fidelity không nằm trong hợp đồng public hiện tại của TokenLab cho gpt-image-2; hãy bỏ trường này, nếu gửi request sẽ trả 400 unsupported_parameter.Thân Yêu Cầu
Timeout cho yêu cầu đồng bộ: một số yêu cầu hình ảnh sẽ trả ảnh cuối cùng inline và chờ quá trình tạo hoàn tất. Yêu cầu độ phân giải cao hoặc chất lượng cao có thể mất gần một phút hoặc lâu hơn, vì vậy hãy đặt timeout của HTTP client ít nhất là120s. Nếu phản hồi tạo có status: "pending", task_id, hoặc poll_url, hãy theo poll_url được trả về để polling.
URL ảnh từ xa: khi cần input multipart, TokenLab sẽ tải JSON image_url, image_urls, hoặc images[].image_url rồi gửi byte dưới dạng các phần multipart image. URL phải là http/https công khai, không chứa credentials nhúng hoặc fragment, và không được resolve tới localhost, dải IP private hoặc reserved; mỗi redirect đều được kiểm tra lại. Payload tải về phải là ảnh PNG, JPEG hoặc WebP thật. Giới hạn: 50MB mỗi ảnh, tổng 200MB cho ảnh tải từ URL trong một request, timeout tải 10s, và tối đa 3 redirect.
Ảnh nguồn multipart. Lặp lại trường
image để gửi nhiều nguồn GPT Image. File phải là PNG, JPEG hoặc WebP, tối đa 16 ảnh nguồn và 50MB mỗi ảnh. Model edit xAI Grok Imagine dùng cùng các trường input nhưng giới hạn ảnh nguồn ở mức 3.Mô tả bằng văn bản cho chỉnh sửa mong muốn.
Một ảnh bổ sung có các vùng trong suốt hoàn toàn để chỉ ra nơi ảnh sẽ được chỉnh sửa. Phải là tệp PNG hợp lệ, nhỏ hơn 50MB, và có cùng kích thước với
image.Với yêu cầu JSON, mask cũng có thể là một object chứa đúng một trong hai trường image_url hoặc file_id; giá trị file_id phải đến từ /v1/files và vẫn gắn với cùng cấu hình chỉnh sửa ảnh.Model dùng cho edit ảnh. Dùng
gpt-image-2 cho edit GPT Image, hoặc một model edit ảnh hiện tại được trả về bởi GET /v1/models?recommended_for=image.Số lượng ảnh cần tạo. Phải nằm trong khoảng từ 1 đến 10.
Kích thước ảnh được tạo. Với
gpt-image-2, dùng auto hoặc WIDTHxHEIGHT; kích thước phải là bội số của 16, cạnh dài nhất tối đa 3840px, tỷ lệ cạnh dài/ngắn tối đa 3:1, và tổng pixel nằm trong khoảng 655,360 đến 8,294,400.Định dạng trả về của ảnh được tạo. Phải là
url hoặc b64_json; mặc định là url.Với gpt-image-2 qua Azure Official hoặc dịch vụ tương thích Azure, TokenLab nhận kết quả ảnh dưới dạng b64_json. Với request url, TokenLab tải từng ảnh lên CDN rồi trả về data[].url. Nếu CDN storage không khả dụng hoặc upload thất bại, request sẽ thất bại và không chuyển thành response Base64. Với b64_json, Base64 gốc được trả về.Đặt
true với gpt-image-2 hoặc các model edit FLUX/BFL chính thức để trả về task trước khi ảnh cuối sẵn sàng. Edit async hoàn tất trả về URL bất kể response_format được yêu cầu; dùng request đồng bộ nếu cần b64_json.Một định danh duy nhất đại diện cho end-user của bạn để theo dõi lạm dụng.
Phản Hồi
Unix timestamp lúc ảnh được tạo.
Mảng các ảnh được tạo.Mỗi object chứa:
url(string): URL của ảnh đã chỉnh sửa (nếu response_format làurl)b64_json(string): Ảnh mã hoá Base64 (nếu response_format làb64_json)
Phản hồi task async
Đặtasync: true với gpt-image-2 hoặc các model edit FLUX/BFL chính thức để tạo task thay vì chờ ảnh đã chỉnh sửa trong request. Phản hồi gồm status: "pending", task_id và poll_url. Hãy poll /v1/tasks/{task_id} cho đến khi task chuyển sang completed hoặc failed.
Task edit async chỉ trả về URL của ảnh cuối. Nếu cần dữ liệu ảnh thô b64_json, hãy dùng request đồng bộ.
Khi tạo tác vụ, hệ thống có thể tạm giữ chi phí ước tính. Tác vụ hoàn tất được tính theo mức sử dụng thực tế; tác vụ thất bại hoặc hết hạn sẽ được giải phóng khoản tạm giữ hoặc hoàn phí.
Ghi Chú
Lỗi tải ảnh từ xa được trả về như lỗi input trước khi quá trình tạo bắt đầu. URL không truy cập được, timeout, phản hồi 403/404, host private/internal, credentials hoặc fragment trong URL, nội dung không phải ảnh, định dạng không hỗ trợ, và vượt giới hạn kích thước sẽ trả
400 hoặc 413 và chỉ ra input image_url / image_urls[n]. Với tài sản private hoặc được bảo vệ bằng header, hãy upload trực tiếp file multipart image hoặc tạo tham chiếu /v1/files.