Định dạng hình ảnh OpenAI

Thông tin chung

• Base URL: https://api.routeapi.ai
• Xác thực: Authorization: Bearer $ROUTEAPI_KEY với API Key bắt đầu bằng sk- (tạo tại trang API Key). Khóa quản lý bắt đầu bằng rat_ không thể gọi mô hình.
• Định dạng lỗi: {"error": {"message": "...", "type": "...", "code": "..."}}; ý nghĩa mã trạng thái xem tại Lỗi thường gặp.

RouteAPI cung cấp khả năng tạo hình ảnh qua các endpoint images tương thích OpenAI. Trang này trình bày khung yêu cầu dùng chung và dòng OpenAI gpt-image — mô hình đang bán là gpt-image-2. Các nhà cung cấp khác được chuyển đổi sang cùng endpoint; hành vi riêng của từng mô hình được mô tả riêng: Nano Banana cho mô hình hình ảnh Gemini, Seedream cho ByteDance.

Việc một mô hình có thể tạo hình ảnh hay không được thể hiện trong danh sách mô hình: supported_endpoint_types của nó chứa image-generation. Xem Mô hình để biết cách đọc trường này.

Endpoint

POST /v1/images/generations
POST /v1/images/edits

URL đầy đủ:

https://api.routeapi.ai/v1/images/generations
https://api.routeapi.ai/v1/images/edits

/v1/images/generations nhận body JSON. /v1/images/edits nhận multipart/form-data — hoặc, trên các kênh tương thích OpenAI, một body JSON tham chiếu hình ảnh bằng URL hoặc Base64 (xem Chỉnh sửa bằng JSON).

Tạo hình ảnh

Tham số yêu cầu

Trường	Kiểu	Bắt buộc	Mô tả
model	string	Có	ID mô hình lấy từ GET /v1/models, ví dụ gpt-image-2
prompt	string	Có	Mô tả văn bản của hình ảnh cần tạo
n	integer	Không	Số lượng hình ảnh, tối đa 128. Bỏ qua hoặc đặt 0 được coi là 1
size	string	Không	Kích thước đầu ra như 1024x1024, 1024x1536, hoặc một bậc như 1K / 2K, tùy mô hình. Trong body JSON, dùng x làm dấu phân cách — ký tự × toàn phần sẽ bị từ chối với 400
quality	string	Không	Mức chất lượng như standard, hd, high, medium, low hoặc auto. Giá trị được chấp nhận tùy mô hình
response_format	string	Không	url hoặc b64_json. Được chuyển tiếp tới upstream; giá trị nào được mô hình tuân theo do nhà cung cấp quyết định
style	string	Không	Gợi ý phong cách (ví dụ vivid hoặc natural). Chỉ có ý nghĩa với mô hình chấp nhận nó
user	string	Không	Định danh người dùng cuối, được chuyển tiếp tới upstream
watermark	boolean	Không	Có đóng dấu watermark lên đầu ra hay không, với nhà cung cấp hỗ trợ

Các trường bổ sung mà gateway hiểu gồm background, output_format, output_compression, input_fidelity, moderation và partial_images; khi có mặt chúng được chuyển tiếp tới upstream tương thích OpenAI. Các trường JSON không nhận diện được sẽ bị loại bỏ, không được chuyển tiếp, trừ khi kênh đang ở chế độ chuyển tiếp nguyên body.

Ghi chú

Giá trị mặc định phụ thuộc từng mô hình. Gateway chèn quality: "auto" cho gpt-image-1 khi tạo bằng JSON và không chèn mặc định cho gpt-image-2. Mô hình cũ dall-e-3 mặc định size: "1024x1024" và quality: "standard", chỉ chấp nhận 1024x1024, 1024x1792 và 1792x1024.

prompt là bắt buộc ở phía mô hình upstream nhưng RouteAPI không từ chối trước: prompt rỗng vẫn được chuyển tiếp, và nhà cung cấp quyết định có báo lỗi hay không.

n lớn hơn 128 sẽ bị từ chối trước khi chuyển tiếp yêu cầu.

Ví dụ yêu cầu

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A calico cat playing a piano on a small stage, soft studio lighting",
    "size": "1024x1024",
    "n": 1
  }'

Python (OpenAI SDK)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="A calico cat playing a piano on a small stage, soft studio lighting",
    size="1024x1024",
    n=1,
)

for item in result.data:
    print(item.url or item.b64_json[:40])

Phản hồi

Các kênh tương thích OpenAI trả nguyên body từ upstream. Tùy mô hình, data[] chứa b64_json, url hoặc cả hai — hãy đọc trường nào có mặt.

{
  "created": 1740000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 4160,
    "total_tokens": 4172
  }
}

Trường	Mô tả
created	Dấu thời gian Unix của lần tạo
data	Mảng hình ảnh đã tạo, mỗi hình một phần tử
data[].url	URL hình ảnh, khi upstream trả URL
data[].b64_json	Byte hình ảnh dạng Base64, khi upstream trả Base64
data[].revised_prompt	Prompt được viết lại, nếu mô hình trả về
usage	Lượng token, chỉ có khi upstream trả về

Đọc trường url / b64_json nào có mặt; đừng giả định cả hai cùng tồn tại, và coi usage là tùy chọn khi phân tích.

Chỉnh sửa hình ảnh

POST /v1/images/edits thay đổi hình ảnh hiện có bằng prompt và, tùy chọn, một mask.

Trường multipart

Trường	Kiểu	Bắt buộc	Mô tả
model	string	Có	ID mô hình lấy từ GET /v1/models
image	file	Có	Hình ảnh nguồn. Lặp lại trường hoặc dùng image[] để gửi nhiều ảnh
prompt	string	Có	Chỉ dẫn mô tả việc chỉnh sửa
mask	file	Không	Ảnh mask đánh dấu vùng cần chỉnh sửa. Ý nghĩa mask do mô hình upstream quy định
n	integer	Không	Số kết quả, tối đa 128 (mặc định 1)
size	string	Không	Kích thước đầu ra, theo cùng quy tắc như khi tạo
quality	string	Không	Mức chất lượng mô hình chấp nhận
watermark	boolean	Không	Có đóng dấu watermark lên đầu ra hay không

Các trường form khác được chuyển nguyên tới upstream tương thích OpenAI, nên các tham số như response_format hay input_fidelity cũng đi qua.

Ví dụ yêu cầu multipart

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F model="gpt-image-2" \
  -F prompt="Replace the background with a sunset beach" \
  -F image=@"cat.png" \
  -F size="1024x1024"

Python (OpenAI SDK)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

with open("cat.png", "rb") as image:
    result = client.images.edit(
        model="gpt-image-2",
        image=image,
        prompt="Replace the background with a sunset beach",
        size="1024x1024",
    )

print(result.data[0].b64_json[:40])

Chỉnh sửa bằng JSON

Trên các kênh tương thích OpenAI, /v1/images/edits cũng nhận body JSON. RouteAPI tải hoặc giải mã từng tham chiếu hình ảnh rồi dựng lại yêu cầu multipart cho upstream — dùng cách này khi hình ảnh đã nằm ở URL hoặc là chuỗi Base64.

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Repaint this photo as a watercolor illustration",
    "images": [
      { "image_url": "https://example.com/photo.png" }
    ],
    "size": "1024x1024"
  }'

Mỗi phần tử trong images có thể chứa image_url (hoặc url) là liên kết http(s) hoặc chuỗi data:image/...;base64,.... mask dùng cùng cấu trúc. Trên đường dẫn này mảng images là bắt buộc; trường image đơn lẻ không được đọc. Các họ kênh khác có thể vẫn yêu cầu body multipart thật, nên hãy thử với mô hình mục tiêu trước khi dựa vào chỉnh sửa bằng JSON.

Các nhà cung cấp khác trên cùng endpoint

Endpoint và khung prompt / n / size là dùng chung, nhưng mỗi adapter nhà cung cấp ánh xạ chúng theo cách khác nhau.

Họ nhà cung cấp	Trang
Mô hình hình ảnh Google Gemini (gemini-*-image*)	Nano Banana
ByteDance Seedream (seedream-5.0-pro, seedream-5.0-lite)	Seedream

Tính phí

Mô hình gpt-image tính phí theo token: hình ảnh tạo ra được tính là token đầu ra theo giá đầu ra, còn prompt và ảnh tham chiếu tính là token đầu vào. Đầu ra lớn hơn và chất lượng cao hơn tiêu tốn nhiều token hơn. Quy tắc đầy đủ xem tại Giá mô hình, và trang chi tiết mô hình cho biết áp dụng cách nào.

Trên các mô hình tính phí theo ảnh có bậc kích thước, giá được chọn theo số pixel của size yêu cầu trước khi chọn kênh; n tính phí theo từng ảnh, và size bị bỏ qua hoặc không nhận diện được sẽ dùng đơn giá cao nhất.

Lỗi và giới hạn

Trạng thái	Ý nghĩa	Nguyên nhân thường gặp
400	Yêu cầu không hợp lệ	Thiếu model, n lớn hơn 128, size không được mô hình hỗ trợ, dùng × làm dấu phân cách kích thước trong body JSON
401	Xác thực thất bại	API Key thiếu, không hợp lệ, hết hạn hoặc hết hạn mức
403	Hết số dư hoặc hạn mức	insufficient_user_quota hoặc pre_consume_token_quota_failed; nạp thêm hoặc nâng hạn mức Key
429	Bị giới hạn tần suất	Giảm số yêu cầu đồng thời
500	Lỗi chuyển đổi hoặc nội bộ	Không chuyển đổi được yêu cầu cho kênh đã chọn, hoặc yêu cầu chỉnh sửa không có hình ảnh dùng được
501	api_not_implemented	Endpoint tồn tại nhưng không được hỗ trợ

POST /v1/images/variations không được hỗ trợ và trả 501 với mã api_not_implemented; hãy dùng chỉnh sửa dựa trên prompt. /v1/images/edits cần ít nhất một hình ảnh — tên trường form image, image[] và dạng image[0] đều được nhận diện.

Bước tiếp theo

• Nano Banana — mô hình hình ảnh Gemini, gồm đường dẫn generateContent gốc.
• Seedream — kích thước, tạo ảnh tuần tự và chỉnh sửa của ByteDance Seedream.
• Mô hình — tìm mô hình hình ảnh và xác nhận hỗ trợ image-generation.
• Giá mô hình — tính phí theo token và theo ảnh, bậc kích thước.
• Lỗi thường gặp — mã trạng thái dùng chung và định dạng body lỗi.