Hướng dẫn media
Tạo ảnh
Tạo hoặc chỉnh sửa hình ảnh và xử lý các tệp đã hoàn thành hoặc các tác vụ bất đồng bộ
TokenLab hỗ trợ chuyển đổi văn bản thành ảnh (text-to-image), ảnh thành ảnh (image-to-image) và chỉnh sửa hình ảnh. Các tham số khác nhau tùy theo từng model, vì vậy hãy kiểm tra các trường yêu cầu của model đã chọn trước khi gửi yêu cầu.
Chọn endpoint
| Bạn cần gì | Endpoint | Sử dụng khi | Không dành cho |
|---|---|---|---|
| Text-to-image | POST /v1/images/generations | Người dùng chỉ bắt đầu với văn bản | Chỉnh sửa tệp GPT Image hiện có |
| Image-to-image | POST /v1/images/generations | Model chấp nhận operation: "image-to-image" và các URL ảnh | Các model yêu cầu đầu vào chỉnh sửa multipart |
| Chỉnh sửa ảnh | POST /v1/images/edits | Một model chỉnh sửa được hỗ trợ thay đổi ảnh hiện có | Tạo tham chiếu kiểu Nano Banana |
| Biến thể | POST /v1/images/variations | Một tích hợp hiện có đã sử dụng API biến thể | Một tính năng ảnh tham chiếu mới |
| Trạng thái | GET /v1/tasks/{id} | Phản hồi tạo trả về task_id, status: "pending", hoặc poll_url | Phản hồi tạo đã chứa data[] cuối cùng |
Luôn gửi model; các API hình ảnh không tự chọn model mặc định cho bạn.
Chọn model
Tìm các model hình ảnh hiện tại với:
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
-H "Authorization: Bearer sk-your-api-key"Mở chi tiết của model đã chọn để xác nhận:
- Thao tác được hỗ trợ, chẳng hạn như
text-to-image,image-to-image, hoặcimage-edit. - Endpoint yêu cầu mà model mong đợi.
- Cách gửi tham chiếu:
image_url,image_urls,reference_image_urls, multipartimage, hoặc JSONimages[]. - Liệu model có chấp nhận
size,aspect_ratio,resolution,quality,background,output_format, hoặcresponse_formathay không.
Các trường dành riêng cho model
- Các yêu cầu kiểu
gpt-image-2sử dụng các trườngsize,qualityvà chỉnh sửa giống như OpenAI. Đối với việc tạo và chỉnh sửa với model này,backgroundchấp nhậnautohoặcopaque;transparentkhông được hỗ trợ. Bỏ qua các trường tùy chọn để sử dụng mặc định tự động. - Các dòng model hình ảnh Gemini và Nano Banana thường sử dụng
aspect_ratio; chỉ gửiresolutionkhi chi tiết model hiển thị nó. Trên các model có các cấp độ phân giải,sizelà1K,2K, hoặc4Kđược gửi dưới dạngresolution; một cấp độ khác vớiresolutionsẽ bị từ chối. - Nano Banana image-to-image thuộc về
/v1/images/generationsvớioperation: "image-to-image"và các URL ảnh tham chiếu. /v1/images/generationskhông chấp nhậnimages[]hoặcfile_idở cấp cao nhất; đó là các cấu trúc luồng chỉnh sửa.- Các tham chiếu ảnh từ xa phải là URL
httphoặchttpscông khai. Không gửi URL mạng nội bộ, thông tin xác thực nhúng, phân đoạn URL hoặc URL đã ký có thể hết hạn trước khi quá trình xử lý bắt đầu.
Ví dụ về Text-to-image
curl https://api.tokenlab.sh/v1/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A clean product photo of a ceramic coffee cup on a walnut desk",
"size": "1024x1024",
"response_format": "url"
}'Ví dụ về ảnh tham chiếu
curl https://api.tokenlab.sh/v1/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"operation": "image-to-image",
"prompt": "Keep the product shape, change the background to a bright studio setup",
"image_urls": ["https://example.com/input/product.png"],
"aspect_ratio": "1:1"
}'Nhận hình ảnh
Các phản hồi hình ảnh có thể là đồng bộ hoặc bất đồng bộ:
- Các phản hồi đồng bộ trả về
data[]cuối cùng vớiurlhoặcb64_json. - Các phản hồi bất đồng bộ trả về
id,task_id,statusvà thường làpoll_url. Gửi"async": truetrên một model hỗ trợ thực thi bất đồng bộ công khai để nhận một tác vụ thay vì chờ đợi hình ảnh. - Để kiểm tra một tác vụ bất đồng bộ, hãy gọi
GET /v1/tasks/{id}vớiidhoặctask_idđược trả về. - Sử dụng yêu cầu đồng bộ khi bạn cần
b64_json; các kết quả hình ảnh bất đồng bộ sử dụng URL.
Các URL kết quả hình ảnh là các URL phương tiện của TokenLab có hiệu lực trong 30 ngày. media_retention.items báo cáo trạng thái lưu của từng mục và expires_at; phản hồi có thể bỏ qua media_retention khi trạng thái lưu không được biết kịp thời, và URL vẫn hoạt động. Các kết quả Base64 nội dòng nằm ngoài phạm vi lưu giữ URL này. Việc lưu thủ công một hình ảnh vào Thư viện phương tiện sẽ cung cấp cho nó một vòng đời riêng. Xem Lưu giữ dữ liệu.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Lưu trữ URL hình ảnh, ID tác vụ, model và ID người dùng/công việc của riêng bạn. Không tiếp tục thăm dò (polling) sau khi đạt trạng thái cuối cùng.
Trước khi ra mắt
- Xác thực đầu vào của người dùng trước khi gọi TokenLab: độ dài prompt, số lượng ảnh, khả năng truy cập URL và loại tệp.
- Đặt thời gian chờ HTTP đủ cao cho các yêu cầu độ phân giải cao đồng bộ. Sử dụng
async: trueở nơi model hỗ trợ cho các tác vụ dài. - Lưu trữ
request_id,task_id,poll_url, model, endpoint và các tên trường đã gửi. - Khi một yêu cầu hình ảnh trả về một tác vụ,
Idempotency-Keygiúp yêu cầu tạo an toàn để thử lại: sau khi máy khách hết thời gian chờ, hãy gửi cùng một yêu cầu với cùng một khóa để nhận tác vụ đó. Đối với một yêu cầu trả về hình ảnh trực tiếp, việc thử lại với cùng một khóa có thể trả về trạng thái tác vụ thay vì hình ảnh, hoặc409vớiidempotent_response_not_replayable. Nếu không có khóa, hãy kiểm tra xem tác vụ đã được tạo trước khi bạn thử lại hay không. - Sử dụng Usage và
billing_transaction_idcho khoản phí cuối cùng.
Các lỗi thường gặp
| Triệu chứng | Nguyên nhân có thể | Khắc phục |
|---|---|---|
400 với param: "model" | Thiếu model cụ thể | Truy vấn /v1/models?recommended_for=image và gửi model |
| Trường không được hỗ trợ | Trường không được ghi lại cho model đó | Xóa trường hoặc chọn model/endpoint có ghi lại trường đó |
Không có b64_json trên kết quả bất đồng bộ | Các tác vụ hình ảnh bất đồng bộ trả về kết quả theo hướng URL | Sử dụng chế độ đồng bộ cho đầu ra base64 |
| Ảnh tham chiếu bị từ chối | Sai endpoint hoặc URL riêng tư/đã hết hạn | Khớp với cấu trúc tham chiếu được ghi lại của model và sử dụng các URL có thể truy cập được |
Tham chiếu API
| Chủ đề | Tham chiếu |
|---|---|
| Tạo ảnh | Tạo ảnh |
| Chỉnh sửa ảnh | Chỉnh sửa ảnh |
| Tạo biến thể ảnh | Tạo biến thể ảnh |
| Nhận trạng thái ảnh | Nhận trạng thái ảnh |
| Nhận trạng thái tác vụ | Nhận trạng thái tác vụ |