TokenLab

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ìEndpointSử dụng khiKhông dành cho
Text-to-imagePOST /v1/images/generationsNgười dùng chỉ bắt đầu với văn bảnChỉnh sửa tệp GPT Image hiện có
Image-to-imagePOST /v1/images/generationsModel chấp nhận operation: "image-to-image" và các URL ảnhCác model yêu cầu đầu vào chỉnh sửa multipart
Chỉnh sửa ảnhPOST /v1/images/editsMộ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/variationsMộ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áiGET /v1/tasks/{id}Phản hồi tạo trả về task_id, status: "pending", hoặc poll_urlPhả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ặc image-edit.
  • Endpoint yêu cầu mà model mong đợi.
  • Cách gửi tham chiếu: image_url, image_urls, reference_image_urls, multipart image, hoặc JSON images[].
  • Liệu model có chấp nhận size, aspect_ratio, resolution, quality, background, output_format, hoặc response_format hay không.

Các trường dành riêng cho model

  • Các yêu cầu kiểu gpt-image-2 sử dụng các trường size, quality và 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, background chấp nhận auto hoặc opaque; transparent khô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ửi resolution khi chi tiết model hiển thị nó. Trên các model có các cấp độ phân giải, size là 1K, 2K, hoặc 4K được gửi dưới dạng resolution; một cấp độ khác với resolution sẽ bị từ chối.
  • Nano Banana image-to-image thuộc về /v1/images/generations với operation: "image-to-image" và các URL ảnh tham chiếu.
  • /v1/images/generations không chấp nhận images[] hoặc file_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 http hoặc https cô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ới url hoặc b64_json.
  • Các phản hồi bất đồng bộ trả về id, task_id, status và thường là poll_url. Gửi "async": true trê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ới id hoặc task_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-Key giú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ặc 409 với idempotent_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_id cho khoản phí cuối cùng.

Các lỗi thường gặp

Triệu chứngNguyê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 URLSử dụng chế độ đồng bộ cho đầu ra base64
Ảnh tham chiếu bị từ chốiSai endpoint hoặc URL riêng tư/đã hết hạnKhớ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 ảnhTạo ảnh
Chỉnh sửa ảnhChỉnh sửa ảnh
Tạo biến thể ảnhTạo biến thể ảnh
Nhận trạng thái ảnhNhận trạng thái ảnh
Nhận trạng thái tác vụNhận trạng thái tác vụ

Trên trang này