Hình ảnh
Chỉnh sửa hình ảnh
Chỉnh sửa hình ảnh dựa trên prompt và hình ảnh nguồn
Tổng quan
Tạo một hình ảnh đã chỉnh sửa hoặc mở rộng dựa trên hình ảnh gốc và prompt.
Endpoint này hỗ trợ cả hai:
- luồng tải lên
multipart/form-datatương thích với OpenAI được ghi chép bên dưới - các yêu cầu JSON cung cấp
image_url,image_urls, hoặc các tham chiếuimageschính thức cho các họ image-to-image được hỗ trợ
gpt-image-2 được hỗ trợ tại đây. Model này chấp nhận tải lên multipart image, JSON image_url / image_urls, 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. Tạo các giá trị file_id thông qua /v1/files trước. Đặt async: true để trả về một task trước; mọi model liệt kê async trong các tham số được hỗ trợ, chẳng hạn như gpt-image-2 và các model chỉnh sửa FLUX, đều sử dụng cùng một luồng thăm dò task.
Các chỉnh sửa của gpt-image-2 không chấp nhận resolution; 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 nhiều hình ảnh hoặc có độ trễ cao, hãy ưu tiên đặt async: true và thăm dò task được trả về.
Các yêu cầu hình ảnh tham chiếu Nano Banana (nano-banana-2, nano-banana-2.1, nano-banana-2-lite, và nano-banana-pro) được cung cấp 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 image-edit. 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 model chỉnh sửa hình ảnh xAI Grok Imagine chấp nhận số lượng hình ảnh nguồn giới hạn: grok-imagine-image-2.0 chấp nhận tối đa 5, và grok-imagine-image chấp nhận tối đa 3. Các yêu cầu có nhiều hình ảnh nguồn hơn mức model chấp nhận sẽ không vượt qua bước xác thực đầu vào với lỗi 400 too_many_images. Các yêu cầu image-to-image của chúng cũng sử dụng endpoint này.
Chi tiết của từng model (GET /v1/models/{model}, xem Lấy Model) cung cấp endpoint cho từng thao tác trong tokenlab.request_format_summary.request_endpoint_by_operation, cùng các trường được chấp nhận và giới hạn trong tokenlab.request_format_details.operation_constraints. Một thao tác được gửi đến sai endpoint sẽ trả về 400 unsupported_endpoint.
input_fidelity không nằm trong các trường hiện được TokenLab hỗ trợ cho gpt-image-2; hãy bỏ qua trường này 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 (inline) và đợi quá trình tạo hoàn tất. Các 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 thời gian chờ của HTTP client tối thiểu là 120s. Nếu phản hồi tạo chứa status: "pending", task_id, hoặc poll_url, hãy thăm dò GET /v1/tasks/{task_id} thay thế.
URL hình ảnh từ xa: khi cần đầu vào multipart, TokenLab sẽ tải JSON image_url, image_urls, hoặc images[].image_url và gửi các byte dưới dạng các phần image multipart. URL phải là http/https công khai, không chứa thông tin xác thực hoặc fragment nhúng bên trong, và không được phân giải về localhost, dải IP riêng tư hoặc dải IP dành riêng; mỗi lần chuyển hướng đều được kiểm tra lại. Dữ liệu tải về phải là hình ảnh PNG, JPEG, hoặc WebP hợp lệ. Các giới hạn gồm 50 MiB cho mỗi hình ảnh, tổng cộng 200 MiB cho các hình ảnh tải từ URL trong một yêu cầu, thời gian chờ tải 30s, và tối đa 3 lần chuyển hướng.
Đố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 images[] phải chứa chính xác một trong hai trường image_url hoặc file_id. Giới hạn tổng 200 MiB bao gồm tất cả các hình ảnh nguồn và mask.
Hình ảnh nguồn multipart. Lặp lại image để cung cấp nhiều nguồn GPT Image. Tệp phải là PNG, JPEG, hoặc WebP, tối đa 16 hình ảnh nguồn và 50 MiB mỗi ảnh. Các model chỉnh sửa xAI Grok Imagine sử dụng cùng các trường đầu vào này nhưng giới hạn hình ảnh nguồn: tối đa 5 cho grok-imagine-image-2.0 và tối đa 3 cho các model chỉnh sửa xAI khác.
Mô tả bằng văn bản về chỉnh sửa mong muốn, tối đa 32.000 ký tự. Bắt buộc đối với mọi model có thông tin chi tiết liệt kê prompt. Các công cụ không có prompt, chẳng hạn như stability-upscale-fast, được gọi mà không cần trường này.
Một hình ảnh bổ sung có các vùng hoàn toàn trong suốt biểu thị vị trí hình ảnh cần được chỉnh sửa. Phải là tệp PNG hợp lệ, dung lượng dưới 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 chứa chính xác một trong hai trường image_url hoặc file_id; các giá trị file_id phải đến từ /v1/files và vẫn liên kết với cùng một cấu hình image-edit.
Model sử dụng cho các thao tác 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 model image-edit hiện tại khác được trả về bởi GET /v1/models?recommended_for=image.
1Số lượng hình ảnh cần tạo (1-10, tùy thuộc vào model).
Kích thước của hình ảnh được tạo. Đối với gpt-image-2, 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ệ dài/ngắn tối đa 3:1, và tổng số pixel 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 model hoặc một cấp độ phân giải: 1K, 2K, hoặc 4K. TokenLab gửi cấp độ này dưới dạng resolution. Một cấp độ mà model không hỗ trợ, hoặc cấp độ khác với resolution, sẽ trả về lỗi 400 với mã invalid_image_size_contract. Dạng được khuyến nghị là aspect_ratio kết hợp với resolution.
Cách các hình ảnh được trả về: url hoặc b64_json.
- Bỏ qua: khi model trả về các byte hình ảnh, mỗi hình ảnh sẽ nằm trong
data[].b64_json, và cũng nằm trongdata[].urlkhi TokenLab đã lưu trữ nó. Khi model trả về một liên kết, mỗi hình ảnh sẽ nằm trongdata[].url. url: mỗi hình ảnh chỉ nằm trongdata[].url.b64_json: mỗi hình ảnh chỉ nằm trongdata[].b64_jsondưới dạng dữ liệu Base64.
Các liên kết là URL kết quả media của TokenLab. Chúng có hiệu lực trong 30 ngày. Xem Lưu giữ dữ liệu.
falseĐặt thành true để trả về một task trước khi hình ảnh cuối cùng sẵn sàng. Chỉ những model liệt kê async trong số các tham số được hỗ trợ mới chấp nhận trường này, ví dụ gpt-image-2; đối với bất kỳ model nào khác, yêu cầu sẽ trả về 400 unsupported_async_mode. Các chỉnh sửa async đã hoàn thành sẽ trả về URL bất kể response_format được yêu cầu là gì; hãy sử dụng yêu cầu đồng bộ khi bạn cần b64_json.
Định danh duy nhất đại diện cho người dùng cuối của bạn nhằm mục đích giám sát lạm dụng.
Phản hồi
Unix timestamp thời điểm hình ảnh được tạo.
Mảng chứa các hình ảnh đã tạo.
Mỗi đối tượng bao gồm:
url(string): URL kết quả media TokenLab của hình ảnh đã chỉnh sửa, có hiệu lực trong 30 ngày. Không xuất hiện khiresponse_formatlàb64_json. Khiresponse_formatbị bỏ qua, trường này sẽ không có nếu TokenLab không thể lưu trữ hình ảnh.b64_json(string): Dữ liệu hình ảnh Base64. Xuất hiện khiresponse_formatlàb64_json, hoặc khi bị bỏ qua và model trả về các byte hình ảnh.
Số lượng token (input_tokens, output_tokens, total_tokens, và chi tiết của chúng) đối với các model tính giá theo token chẳng hạn như gpt-image-2, khi khả dụng.
Phản hồi Async Task
Đặt async: true trên model có hỗ trợ để tạo một task thay vì đợ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. Thăm dò /v1/tasks/{task_id} cho đến khi task đạt trạng thái completed hoặc failed.
Các task chỉnh sửa async 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ộ.
Hệ thống thanh toán có thể tạm giữ số tiền ước tính khi task được tạo. Các task hoàn thành được tính phí theo mức sử dụng thực tế, và các task 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
{
"created": 1706000000,
"data": [
{
"url": "https://..."
}
]
}Ghi chú
Lỗi tải 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, host riêng tư/nội bộ, thông tin xác thực hoặc fragment 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ề lỗi 400 hoặc 413 và chỉ rõ đầu vào image_url / image_urls[n]. Mã lỗi là invalid_image_url, unsupported_image_content_type, too_many_images, hoặc đối với 413 là image_too_large hoặc image_input_too_large. Đố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 trực tiếp các tệp image dạng multipart hoặc tạo tham chiếu /v1/files.
Gửi header Idempotency-Key để thử lại yêu cầu một cách an toàn sau khi hết thời gian chờ; xem Thử lại an toàn với khóa idempotency.
Hy Image 3.5 Preview chỉnh sửa hình ảnh tham chiếu dựa trên hướng dẫn bằng văn bản. Model này chỉ chấp nhận size là 1024x1024 và n là 1:
{
"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 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
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"
Khóa tùy chọn giúp yêu cầu hình ảnh trở nên an toàn khi thử lại nếu yêu cầu đó đã tạo một tác vụ. Hãy gửi một giá trị duy nhất mới, chẳng hạn như UUID, cho mỗi yêu cầu. Thử lại với cùng khóa và cùng phần thân sẽ trả về tác vụ đó và không tạo, điều phối hoặc tính phí tác vụ thứ hai. Đối với yêu cầu trả về hình ảnh trực tiếp, thử lại với cùng khóa có thể trả về trạng thái tác vụ thay vì hình ảnh, hoặc 409 kèm idempotent_response_not_replayable. Phần thân khác với khóa đã được chấp nhận sẽ bị từ chối; mã trạng thái và mã lỗi cho trường hợp này không được đảm bảo. Khóa dài hơn 255 ký tự sẽ bị bỏ qua và yêu cầu đó sẽ không có bảo vệ idempotency. Xem Thử lại an toàn với khóa idempotency.
1 <= length <= 255Phản hồi
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json