Chỉnh sửa hình ảnh

Chỉnh sửa hình ảnh dựa trên câu lệnh (prompt) và hình ảnh nguồn

Tổng quan

Tạo một hình ảnh đã được chỉnh sửa hoặc mở rộng dựa trên hình ảnh gốc và câu lệnh.

Endpoint này hỗ trợ cả hai phương thức:

Luồng tải lên multipart/form-data tương thích với OpenAI được ghi lại bên dưới
Các 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 image-to-image được hỗ trợ

gpt-image-2 được hỗ trợ tại đây. Nó chấp nhận tải lên image dạng multipart, image_url / image_urls dạng JSON, và các tham chiếu images[] chính thức (image_url hoặc file_id), với tối đa 16 hình ảnh nguồn. Hãy tạo các giá trị file_id thông qua /v1/files trước. Thiết lập async: true để trả về một tác vụ trước; các mô hình chỉnh sửa FLUX/BFL chính thức cũng sử dụng cùng một luồng thăm dò tác vụ (task polling).

Các chỉnh sửa bằng gpt-image-2 không chấp nhận resolution; hãy sử dụng size cho kích thước đầu ra. background chấp nhận auto hoặc opaque; transparent không được hỗ trợ. Đối với các chỉnh sửa đa hình ảnh hoặc có độ trễ cao, hãy ưu tiên sử dụng async: true và thăm dò tác vụ được trả về.

Các yêu cầu reference-image của Nano Banana (nano-banana-2, nano-banana-2.1, nano-banana-2-lite, và nano-banana-pro) được hiển thị trên /v1/images/generations với operation: "image-to-image" và image_urls, không phải trên endpoint /v1/images/edits này. Các yêu cầu chỉnh sửa hình ảnh cho nano-banana-2, nano-banana-2.1, nano-banana-2-lite, và nano-banana-pro cũng sử dụng /v1/images/generations, với operation: "image-edit".

gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image, và gemini-3-pro-image sử dụng endpoint này cho việc chỉnh sửa hình ảnh. Các yêu cầu image-to-image của chúng sử dụng /v1/images/generations với operation: "image-to-image".

Các mô hình chỉnh sửa hình ảnh xAI Grok Imagine (grok-imagine-image, grok-imagine-image-quality, và phiên bản cũ grok-imagine-image-pro) chấp nhận tối đa 3 hình ảnh nguồn. Các yêu cầu với hơn 3 hình ảnh nguồn sẽ thất bại trong quá trình xác thực đầu vào với lỗi 400 too_many_images.

input_fidelity không nằm trong các trường được TokenLab hỗ trợ hiện tại cho gpt-image-2; hãy bỏ qua nó nếu không yêu cầu sẽ trả về 400 unsupported_parameter.

Phần thân yêu cầu (Request Body)

Thời gian chờ yêu cầu đồng bộ: Một số yêu cầu hình ảnh trả về hình ảnh cuối cùng trực tiếp và chờ quá trình tạo hoàn tất. 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, vì vậy hãy đặt thời gian chờ (timeout) của HTTP client của bạn ít nhất là 120s. Nếu phản hồi tạo yêu cầu bao gồm status: "pending", task_id, hoặc poll_url, hãy theo dõi poll_url được trả về thay thế.

URL hình ảnh từ xa: khi cần đầu vào multipart, TokenLab sẽ tìm nạp image_url, image_urls, hoặc images[].image_url từ JSON và gửi các byte dưới dạng các phần image multipart. Các URL phải là http/https công khai, không chứa thông tin xác thực hoặc đoạn mã (fragments) nhúng, và không được phân giải thành localhost, mạng riêng tư hoặc các dải IP dành riêng; mỗi lần chuyển hướng (redirect) đều được kiểm tra lại. Payload được tìm nạp phải là hình ảnh PNG, JPEG hoặc WebP thực tế. Các giới hạn là 50 MiB mỗi hình ảnh, tổng cộng 200 MiB cho các hình ảnh được tìm nạp qua URL trong một yêu cầu, thời gian chờ tìm nạp 30s, và tối đa 3 lần chuyển hướng.

Đối với các yêu cầu JSON, hãy 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 images[] phải chứa chính xác một trong các trường image_url hoặc file_id. Giới hạn tổng cộng 200 MiB bao gồm tất cả các hình ảnh nguồn và mặt nạ (mask).

imagefile

Các hình ảnh nguồn multipart. Lặp lại image để cung cấp nhiều nguồn GPT Image. Các tệp phải là PNG, JPEG hoặc WebP, tối đa 16 hình ảnh nguồn và mỗi tệp tối đa 50 MiB. Các mô hình chỉnh sửa xAI Grok Imagine sử dụng các trường đầu vào tương tự nhưng giới hạn hình ảnh nguồn ở mức 3.

promptstringbắt buộc

Mô tả văn bản về chỉnh sửa mong muốn.

maskfile | object

Một hình ảnh bổ sung mà các vùng trong suốt hoàn toàn của nó chỉ ra nơi hình ảnh cần được chỉnh sửa. Phải là tệp PNG hợp lệ, nhỏ hơn 50 MiB và có cùng kích thước với image.

Đối với các yêu cầu JSON, mask cũng có thể là một đối tượng với chính xác một trong các trường image_url hoặc file_id; các giá trị file_id phải đến từ /v1/files và vẫn bị ràng buộc với cùng một cấu hình chỉnh sửa hình ảnh.

modelstringbắt buộc

Mô hình được sử dụng để chỉnh sửa hình ảnh. Sử dụng gpt-image-2 cho các chỉnh sửa GPT Image, hoặc một mô hình chỉnh sửa hình ảnh hiện tại khác được trả về bởi GET /v1/models?recommended_for=image.

nintegermặc định: 1

Số lượng hình ảnh cần tạo (1-10, tùy thuộc vào mô hình).

sizestring

Kích thước của hình ảnh được tạo. Đối với gpt-image-2, hãy sử dụng auto hoặc WIDTHxHEIGHT; các 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 số pixel nằm trong khoảng từ 655,360 đến 8,294,400.

Đối với gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, và gemini-3.1-flash-lite-image, size chấp nhận kích thước đầu ra từ bảng kích thước của mô hình hoặc một cấp độ phân giải: 1K, 2K, hoặc 4K. TokenLab gửi một cấp độ dưới dạng resolution. Một cấp độ mà mô hình không hỗ trợ, hoặc một cấp độ khác với resolution, sẽ trả về 400 với mã invalid_image_size_contract. Hình thức được khuyến nghị là aspect_ratio với resolution.

response_formatstring

Cách thức trả về hình ảnh: url hoặc b64_json.

Bỏ qua: khi mô hình trả về byte hình ảnh, mỗi hình ảnh sẽ nằm trong data[].b64_json, và cũng nằm trong data[].url khi TokenLab đã lưu trữ nó. Khi mô hình trả về một liên kết, mỗi hình ảnh sẽ nằm trong data[].url.
url: mỗi hình ảnh chỉ nằm trong data[].url.
b64_json: mỗi hình ảnh chỉ nằm trong data[].b64_json dưới dạng dữ liệu Base64.

Các liên kết là các URL kết quả phương tiện của TokenLab. Chúng có hiệu lực trong 30 ngày. Xem Lưu giữ dữ liệu.

asyncbooleanmặc định: false

Đặt thành true với gpt-image-2 hoặc các mô hình chỉnh sửa FLUX/BFL chính thức để trả về một tác vụ trước khi hình ảnh cuối cùng sẵn sàng. Các chỉnh sửa không đồng bộ (async) đã hoàn tất sẽ trả về URL bất kể response_format được yêu cầu; hãy sử dụng các yêu cầu đồng bộ khi bạn cần b64_json.

userstring

Một định danh duy nhất đại diện cho người dùng cuối của bạn để giám sát hành vi lạm dụng.

Phản hồi (Response)

createdinteger

Dấu thời gian Unix về thời điểm hình ảnh được tạo.

dataarray

Mảng các hình ảnh được tạo.

Mỗi đối tượng chứa:

url (string): URL kết quả phương tiện của TokenLab cho hình ảnh đã chỉnh sửa, có hiệu lực trong 30 ngày. Không có mặt khi response_format là b64_json. Khi response_format bị bỏ qua, nó sẽ thiếu nếu TokenLab không thể lưu trữ hình ảnh.
b64_json (string): Dữ liệu hình ảnh Base64. Có mặt khi response_format là b64_json, hoặc khi nó bị bỏ qua và mô hình trả về byte hình ảnh.

Phản hồi tác vụ không đồng bộ (Async Task Response)

Đặt async: true với gpt-image-2 hoặc các mô hình chỉnh sửa FLUX/BFL chính thức để tạo một tác vụ thay vì chờ đợi hình ảnh đã chỉnh sửa trong yêu cầu. Phản hồi bao gồm status: "pending", task_id, và poll_url. Hãy thăm dò /v1/tasks/{task_id} cho đến khi tác vụ đạt trạng thái completed hoặc failed.

Các tác vụ chỉnh sửa không đồng bộ chỉ trả về URL hình ảnh cuối cùng. Nếu bạn cần dữ liệu hình ảnh b64_json thô, hãy sử dụng yêu cầu đồng bộ.

Việc thanh toán có thể giữ lại số tiền ước tính khi tác vụ được tạo. Các tác vụ hoàn thành sẽ được tính phí theo mức sử dụng thực tế, và các tác vụ thất bại hoặc hết thời gian chờ sẽ được giải phóng hoặc hoàn tiền.

Yêu cầu

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@sunlit_lounge.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024"

Phản hồi

Response

{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

Ghi chú

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ờ, phản hồi 403/404, máy chủ riêng tư/nội bộ, thông tin xác thực hoặc đoạn mã 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à xác định đầu vào image_url / image_urls[n]. Đối với các tài sản riêng tư hoặc được bảo vệ bằng tiêu đề, hãy tải lên tệp image multipart trực tiếp hoặc tạo các tham chiếu /v1/files.

Hy Image 3.5 Preview tạo ra các hình ảnh vuông 1024 pixel từ văn bản và chỉnh sửa các hình ảnh tham chiếu bằng các hướng dẫn viết tay. Nó rất hữu ích cho việc phác thảo hình ảnh và tinh chỉnh bố cục.

{
  "model": "hy-image-v3.5-preview",
  "prompt": "Change the table to pale blue",
  "image_url": "https://example.com/reference.png",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}

Xác thực

BearerAuth

AuthorizationBearer <token>

Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.

Vị trí: header

Header

X-TokenLab-Delivery-Policy?string

Chính sách phân phối theo yêu cầu. Ghi đè các mặc định của API key và Workspace. Tự động thử TokenLab Verified trước và có thể chuyển đổi một lần sang Official chỉ trước khi xuất, chấp nhận yêu cầu hoặc tạo tài nguyên cố định.

Giá trị hợp lệ

"auto"
"verified"
"official"

Nội dung yêu cầu

model?string

Mô hình để sử dụng cho việc chỉnh sửa hình ảnh. Hãy gửi tham số này một cách rõ ràng.

prompt?string

image_url*string

URL hình ảnh nguồn đơn lẻ. Được giữ lại để tương thích với TokenLab; hãy sử dụng images cho định dạng JSON chính thức.

Định dạnguri

n?integer

Phạm vi1 <= value

quality?string

size?string

aspect_ratio?string

resolution?string

response_format?string

background?string

Giá trị hợp lệ

"transparent"
"opaque"
"auto"

output_format?string

Giá trị hợp lệ

"png"
"jpeg"
"webp"

output_compression?integer

Phạm vi0 <= value <= 100

compression?integer

Phạm vi0 <= value <= 100

moderation?string

Giá trị hợp lệ

"auto"
"low"

async?boolean

Trả về một tác vụ trước khi hình ảnh đã chỉnh sửa sẵn sàng cho các mô hình hỗ trợ thực thi async công khai.

stream?boolean

Cờ streaming hình ảnh dành riêng. Tuyến đường chỉnh sửa công khai hiện từ chối giá trị true.

user?string

image_urls?array<>

Nhiều URL hình ảnh nguồn. Các bản chỉnh sửa GPT Image chấp nhận tối đa 16 hình ảnh nguồn; các mô hình chỉnh sửa xAI Grok Imagine chấp nhận tối đa 3 hình ảnh nguồn.

Phần tử1 <= items <= 16

images?array<|>

Tham chiếu hình ảnh JSON chính thức cho các bản chỉnh sửa hình ảnh. Cung cấp chính xác một trong hai trường image_url hoặc file_id cho mỗi mục. Các bản chỉnh sửa GPT Image chấp nhận tối đa 16 hình ảnh nguồn; các mô hình chỉnh sửa xAI Grok Imagine chấp nhận tối đa 3 hình ảnh nguồn.

Phần tử1 <= items <= 16

mask?|

Tham chiếu mặt nạ JSON tùy chọn cho các bản chỉnh sửa hình ảnh. Cung cấp chính xác một trong hai trường image_url hoặc file_id. Các yêu cầu multipart cũng có thể gửi mặt nạ dưới dạng một phần tệp.

[key: string]?any

Chỉnh sửa hình ảnh

Tổng quan

Phần thân yêu cầu (Request Body)

Phản hồi (Response)

Phản hồi tác vụ không đồng bộ (Async Task Response)

Ghi chú

Xác thực

Header

Nội dung yêu cầu

Phản hồi

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Chỉnh sửa hình ảnh

Tổng quanCopy Anchor Link

Phần thân yêu cầu (Request Body)Copy Anchor Link

Phản hồi (Response)Copy Anchor Link

Phản hồi tác vụ không đồng bộ (Async Task Response)Copy Anchor Link

Ghi chúCopy Anchor Link

Xác thựcCopy Anchor Link

HeaderCopy Anchor Link

Nội dung yêu cầuCopy Anchor Link

Phản hồiCopy Anchor Link

200application/json

400application/json

401application/json

413application/json

500application/json

503application/json

Tổng quan

Phần thân yêu cầu (Request Body)

Phản hồi (Response)

Phản hồi tác vụ không đồng bộ (Async Task Response)

Ghi chú

Xác thực

Header

Nội dung yêu cầu

Phản hồi

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`