API Tạo và Chỉnh Sửa Hình Ảnh

Sử dụng /v1/images/generations để tạo hình ảnh từ một đoạn văn bản mô tả và /v1/images/edits để chỉnh sửa hình ảnh đầu vào. Cả hai endpoint đều sử dụng định dạng request tương thích với OpenAI Images. Các thao tác khả dụng phụ thuộc vào model và kênh được cung cấp bởi dịch vụ Flatkey của bạn.

Các model hình ảnh Gemini sử dụng endpoint generateContent gốc của Gemini và không thể được gọi thông qua các endpoint OpenAI Images này. Xem hướng dẫn model hình ảnh Gemini.

Tạo hình ảnh

Endpoint

POST https://router.flatkey.ai/v1/images/generations

Headers

Header	Giá trị
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

Các tham số body JSON

string

bắt buộc

ID model hình ảnh được cung cấp bởi dịch vụ Flatkey của bạn, chẳng hạn như "gpt-image-2".

string

bắt buộc

Mô tả văn bản của hình ảnh cần tạo.

string

Kích thước đầu ra, chẳng hạn như "1024x1024". Các giá trị được hỗ trợ phụ thuộc vào model.

string

Chất lượng đầu ra: "low", "medium", hoặc "high". Nếu bỏ qua, giá trị mặc định từ upstream sẽ được sử dụng. Chất lượng cao hơn làm tăng độ trễ và mức sử dụng.

string

Xử lý nền, chẳng hạn như "transparent" hoặc "opaque", khi được model hỗ trợ.

string

Định dạng đầu ra, chẳng hạn như "png", "jpeg", hoặc "webp", khi được model hỗ trợ.

integer

Mức độ nén đầu ra, khi được model hỗ trợ.

string

Mức độ kiểm duyệt nội dung, khi được model hỗ trợ.

string

Kết quả của gpt-image-2 được trả về trong data[].b64_json. URL hình ảnh được lưu trữ không được cung cấp, và response_format: "url" không được hỗ trợ.

integer

Số lượng hình ảnh được yêu cầu. gpt-image-2 hiện chỉ trả về một hình ảnh mỗi request vì công cụ hình ảnh upstream của nó không chấp nhận n. Hãy gửi nhiều request nếu bạn cần nhiều hình ảnh.

boolean

Đặt thành true để nhận phản hồi SSE. Bỏ qua để nhận phản hồi đồng bộ.

Ví dụ request

import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.images.generate(
    model="gpt-image-2",
    prompt="A futuristic city skyline at dusk, cyberpunk style",
    size="1024x1024",
    quality="high",
)

Path("generated.png").write_bytes(
    base64.b64decode(response.data[0].b64_json)
)

import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt: "A futuristic city skyline at dusk, cyberpunk style",
  size: "1024x1024",
  quality: "high",
});

writeFileSync(
  "generated.png",
  Buffer.from(response.data[0].b64_json, "base64"),
);

curl https://router.flatkey.ai/v1/images/generations \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A serene forest clearing with morning mist and sunbeams",
    "size": "1024x1024",
    "quality": "high"
  }'

Chỉnh sửa hình ảnh

/v1/images/edits chấp nhận hình ảnh đầu vào và hướng dẫn chỉnh sửa dưới dạng multipart/form-data.

Endpoint

POST https://router.flatkey.ai/v1/images/edits

Headers

Header	Giá trị
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`multipart/form-data`; curl tự động thêm boundary khi bạn sử dụng `-F`

Các trường form

Trường	Kiểu	Bắt buộc	Mô tả
`model`	string	Có	ID model hình ảnh được cung cấp bởi dịch vụ Flatkey của bạn, chẳng hạn như `gpt-image-2`.
`prompt`	string	Có	Hướng dẫn mô tả cách chỉnh sửa hình ảnh.
`image`	file	Có	Hình ảnh đầu vào ở định dạng PNG, JPEG, hoặc WebP. Đối với nhiều hình ảnh, sử dụng `image[]` hoặc các trường có chỉ số như `image[0]` và `image[1]`.
`mask`	file	Không	Mặt nạ cho inpainting. Các vùng trong suốt xác định khu vực cần vẽ lại.
`size`	string	Không	Kích thước đầu ra. Các giá trị được hỗ trợ phụ thuộc vào model.
`quality`	string	Không	Chất lượng đầu ra: `low`, `medium`, hoặc `high`.
`stream`	boolean	Không	Đặt thành `true` để nhận phản hồi SSE.

Ví dụ request

curl https://router.flatkey.ai/v1/images/edits \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=add a small yellow star in the center" \
  -F "image=@input.png" \
  -F "mask=@mask.png"

Trường mask là tùy chọn. Bỏ qua nó để chỉnh sửa toàn bộ hình ảnh dựa trên prompt. Không đặt header Content-Type thủ công; curl tự động xác định boundary multipart chính xác từ các trường -F.

Nếu mặt nạ được cung cấp bị hỏng, không đọc được, hoặc vượt quá giới hạn dịch vụ, request sẽ thất bại thay vì chuyển sang chỉnh sửa toàn bộ hình ảnh.

Phản hồi

Các request tạo và chỉnh sửa đồng bộ đều trả về cùng một cấu trúc phản hồi. Flatkey trả về hình ảnh dưới dạng dữ liệu base64; nó không cung cấp URL hình ảnh được lưu trữ cho gpt-image-2.

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA...",
      "revised_prompt": "Add a small yellow five-pointed star in the center...",
      "url": ""
    }
  ]
}

Các trường phản hồi

integer

Dấu thời gian Unix khi request hoàn thành.

array

Mảng các đối tượng hình ảnh.

Hiện đối tượng hình ảnh

string

Dữ liệu hình ảnh được mã hóa Base64.

string

Prompt thực tế được model sử dụng sau khi viết lại.

string

Trống đối với gpt-image-2; URL được lưu trữ không được cung cấp.

Đối với các thao tác chỉnh sửa, hình ảnh đầu vào cũng được tính vào mức sử dụng model, vì vậy một lần chỉnh sửa thường tiêu tốn nhiều mức sử dụng hơn so với tạo hình ảnh chỉ từ văn bản.

Streaming

Đặt stream thành true trong body JSON của một request tạo hoặc thêm -F "stream=true" vào một request chỉnh sửa để nhận đầu ra text/event-stream. Sự kiện cuối cùng chứa kết quả hình ảnh, theo sau là data: [DONE].

Sự kiện	Ý nghĩa
`image_generation.completed`	Tạo hình ảnh đã hoàn thành.
`image_edit.completed`	Chỉnh sửa hình ảnh đã hoàn thành.
`[DONE]`	Luồng đã kết thúc.

Hỗ trợ streaming có thể phụ thuộc vào model và kênh được chọn. Đối với các request chất lượng cao đồng bộ, hãy cấu hình thời gian chờ client ít nhất 150 giây.

​Tạo hình ảnh

​Endpoint

​Headers

​Các tham số body JSON

​Ví dụ request

​Chỉnh sửa hình ảnh

​Endpoint

​Headers

​Các trường form

​Ví dụ request

​Phản hồi

​Các trường phản hồi

​Streaming

Tạo hình ảnh

Endpoint

Headers

Các tham số body JSON

Ví dụ request

Chỉnh sửa hình ảnh

Endpoint

Headers

Các trường form

Ví dụ request

Phản hồi

Các trường phản hồi

Streaming