API Chỉnh sửa ảnh GPT trên TokenLab: Endpoint chính xác và các dạng đầu vào hình ảnh

Chỉnh sửa hình ảnh là một trong những phần đòi hỏi nhiều tài nguyên hơn của một sản phẩm AI: người dùng tải lên một bức ảnh, mô tả nội dung cần thay đổi và chờ đợi kết quả. Các tác vụ chỉnh sửa sử dụng nhiều hình ảnh nguồn, khung vẽ lớn hoặc câu lệnh prompt phức tạp hơn sẽ mất nhiều thời gian hơn mức mà một lệnh gọi HTTP đồng bộ thông thường có thể đáp ứng thoải mái. Hướng dẫn này bao gồm endpoint chính xác của TokenLab, hai dạng đầu vào hình ảnh được hỗ trợ, chỉnh sửa đa hình ảnh và lộ trình bất đồng bộ (async) cho các yêu cầu xử lý chậm.

Endpoint

Tính năng chỉnh sửa hình ảnh nằm tại POST /v1/images/edits — lưu ý từ edits ở dạng số nhiều. (Một lỗi phổ biến là viết /images/edit, đây không phải là đường dẫn được ghi trong tài liệu.)

Endpoint này hỗ trợ hai cấu trúc yêu cầu:

• Quy trình tải lên multipart/form-data tương thích với OpenAI.
• Yêu cầu JSON cung cấp image_url, image_urls hoặc các tham chiếu images[] chính thức cho các họ mô hình chuyển đổi hình ảnh sang hình ảnh (image-to-image) được hỗ trợ.

Các trường yêu cầu và phản hồi đầy đủ được ghi lại trong Tài liệu tham khảo API Edit Image.

Những gì gpt-image-2 chấp nhận tại đây

• Tải lên image dạng multipart.
• image_url hoặc image_urls dạng JSON.
• Các tham chiếu images[] chính thức, trong đó mỗi đối tượng chứa chính xác một trong hai trường image_url hoặc file_id.
• Tối đa 16 hình ảnh nguồn cho mỗi yêu cầu.

Một số ràng buộc cần biết trước khi bạn viết mã:

• Tác vụ chỉnh sửa trên gpt-image-2 không chấp nhận resolution; hãy sử dụng size cho kích thước đầu ra (hoặc auto hoặc WIDTHxHEIGHT, với các kích thước là bội số của 16, cạnh dài nhất tối đa 3840px, tỷ lệ dài/ngắn tối đa 3:1).
• background chấp nhận auto hoặc opaque; transparent không được hỗ trợ.
• input_fidelity không nằm trong các trường được hỗ trợ cho gpt-image-2; gửi trường này sẽ trả về lỗi 400 unsupported_parameter.
• Đối với các yêu cầu JSON, chỉ cung cấp chính xác một trong các trường image_url, image_urls hoặc images. Mỗi đối tượng trong images[] phải chứa chính xác một trong hai trường image_url hoặc file_id. Các giá trị cho file_id phải được tạo thông qua /v1/files trước.
• Các yêu cầu hình ảnh tham chiếu Nano Banana thuộc về /v1/images/generations với operation: "image-to-image" và image_urls — không thuộc về /v1/images/edits.

Tải lên Multipart so với Tham chiếu hình ảnh qua JSON

Cả hai cách đều hoạt động cho gpt-image-2. Hãy chọn phương pháp phù hợp với nơi lưu trữ các byte hình ảnh hiện tại của bạn.

Multipart — sử dụng phương pháp này khi ứng dụng đang nắm giữ tệp, cho dù từ tệp người dùng tải lên hay tệp tài nguyên được tạo ra. Lặp lại trường image để gửi nhiều nguồn. Tệp phải ở định dạng PNG, JPEG hoặc WebP, mỗi tệp tối đa 50 MiB.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

URL hình ảnh JSON — sử dụng phương pháp này khi hình ảnh đã tồn tại tại một URL công khai hoặc bạn đã tạo chúng trong một yêu cầu TokenLab trước đó và đã có sẵn URL.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

Các URL từ xa phải là http/https công khai, không chứa thông tin đăng nhập hoặc phân đoạn (fragment) nhúng bên trong và không được phân giải thành localhost, dải IP riêng tư hoặc dải IP dành riêng. TokenLab tìm nạp các byte và chuyển chúng đến mô hình dưới dạng các phần image multipart. Giới hạn cho mỗi hình ảnh là 50 MiB; giới hạn tổng thể cho các hình ảnh được tìm nạp qua URL trong một yêu cầu là 200 MiB; thời gian chờ tìm nạp là 30 giây; hỗ trợ theo tối đa 3 lần chuyển hướng (redirect).

Chỉnh sửa nhiều hình ảnh và polling bất đồng bộ

Chỉnh sửa nhiều hình ảnh là trường hợp rõ ràng nhất để sử dụng async: true. Việc gửi nhiều hình ảnh cùng với một bộ hướng dẫn phức tạp thông qua một lệnh gọi đồng bộ đồng nghĩa với việc giữ kết nối mở trong suốt khoảng thời gian mà mô hình cần. Đặt async: true trên gpt-image-2 (và trên các mô hình chỉnh sửa FLUX/BFL chính thức) để nhận về một tác vụ (task):

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

Thực hiện poll poll_url được trả về, hoặc dự phòng bằng GET /v1/tasks/{task_id}. Các trạng thái gồm có pending, processing, completed và failed. Một tác vụ hình ảnh hoàn thành sẽ trả về data[].url. Kiểm tra mỗi 3–5 giây một lần là đủ; hãy dừng lại khi đạt trạng thái cuối cùng (terminal status) thay vì tiếp tục poll.

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

Các tác vụ chỉnh sửa bất đồng bộ trả về các URL hình ảnh cuối cùng bất kể trường response_format được yêu cầu là gì. Nếu bạn cần dữ liệu thô b64_json, hãy sử dụng một yêu cầu đồng bộ.

Hệ thống thanh toán có thể giữ tạm tính (reserve) số tiền ước tính khi tác vụ được tạo; một tác vụ hoàn thành sẽ được lập hóa đơn theo mức sử dụng thực tế, và một tác vụ thất bại hoặc hết thời gian chờ sẽ giải phóng hoặc hoàn lại khoản tiền tạm giữ. Xem Tác vụ bất đồng bộ và polling để biết toàn bộ vòng đời, và Get Image Status để biết các trường phản hồi.

Khi nào nên sử dụng từng chế độ

Sử dụng async: true khi:

• Bạn đang gửi nhiều hình ảnh nguồn trong một yêu cầu.
• Câu lệnh prompt hoặc bộ hướng dẫn của bạn đủ phức tạp khiến thời gian tạo không thể đoán trước.
• Bạn chạy các tác vụ chỉnh sửa trong một tác vụ nền (background job), hàng đợi (queue) hoặc quy trình theo lô (batch process) thay vì một yêu cầu trực tiếp đối diện với người dùng.

Giữ nguyên chế độ đồng bộ khi:

• Bạn đang thực hiện chỉnh sửa một hình ảnh duy nhất với một câu lệnh prompt ngắn.
• Ứng dụng client của bạn ưu tiên việc thất bại nhanh (fail fast) hơn là polling.

Đối với các lệnh gọi đồng bộ, hãy đặt thời gian chờ (timeout) cho HTTP client của bạn ít nhất là 120s; các yêu cầu có độ 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. Nếu phản hồi khởi tạo vẫn trả về với status: "pending", task_id hoặc poll_url, hãy chuyển sang quy trình polling được trả về.

Các lỗi đầu vào cần lường trước

Các lỗi tìm nạp hình ảnh từ xa được trả về dưới dạng lỗi đầu vào trước khi quá trình tạo bắt đầu. Các URL không thể truy cập, hết thời gian chờ (timeout), phản hồi 403/404, máy chủ riêng tư hoặc nội bộ, thông tin đăng nhập hoặc phân đoạn trong URL, nội dung không phải hình ảnh, định dạng không được hỗ trợ và vi phạm giới hạn kích thước sẽ trả về 400 hoặc 413 và chỉ rõ image_url hoặc image_urls[n] vi phạm. Đối với các tài nguyên riêng tư hoặc được bảo vệ bằng header, hãy tải lên trực tiếp các tệp image dạng multipart, hoặc tạo các tham chiếu /v1/files và truyền chúng dưới dạng images[].file_id.

Các mô hình chỉnh sửa hình ảnh xAI Grok Imagine (ví dụ grok-imagine-image và grok-imagine-image-quality) sử dụng cùng các trường đầu vào này nhưng giới hạn tối đa 3 hình ảnh nguồn; gửi nhiều hơn mức đó sẽ trả về 400 too_many_images.

Danh sách kiểm tra tích hợp

• Nhắm mục tiêu đến POST /v1/images/edits và gửi trường model một cách rõ ràng.
• Chọn tải lên multipart hoặc tham chiếu JSON dựa trên nơi hình ảnh của bạn đang được lưu trữ.
• Chỉ gửi chính xác một trong các trường image_url, image_urls hoặc images[] trong các yêu cầu JSON; mỗi mục trong images[] có chính xác một trong hai trường image_url hoặc file_id.
• Sử dụng async: true cho các chỉnh sửa nhiều hình ảnh hoặc tác vụ nặng; poll poll_url được trả về cho đến khi tác vụ đạt trạng thái completed hoặc failed.
• Đặt thời gian chờ của client ít nhất là 120 giây cho các yêu cầu đồng bộ và xử lý phản hồi pending bằng cách lần theo poll_url.
• Khi client bị timeout, hãy kiểm tra xem tác vụ đã được tạo hay chưa trước khi thử lại yêu cầu khởi tạo để tránh bị tính phí trùng lặp.

Bắt đầu

Truy vấn GET /v1/models?recommended_for=image để xem các mô hình hình ảnh hiện tại, sau đó mở trang chi tiết của mô hình để xác nhận các thao tác và trường yêu cầu được hỗ trợ trước khi gửi yêu cầu. Tạo một khóa API từ bảng điều khiển console để thử nghiệm endpoint chỉnh sửa với chính hình ảnh của bạn.