Tài liệu API tạo ảnh

Tương thích thư viện OpenAI. Đổi địa chỉ và key là chạy được: ảnh vuông, dọc 9:16, ngang 16:9, nền trong suốt, chữ tiếng Việt có dấu.

Thông tin kết nối

Bạn cần làm gì?

Bắt đầu nhanh

Từ lúc nhận key đến ảnh đầu tiên chỉ mất vài phút.

1. Nhận API keyBên cung cấp gửi cho bạn một key dạng sk-…. Giữ kín key này.
2. Cài thư viện
   PythonNode.js

   pip install openai pillow

   npm install openai

3. Gọi thử tạo ảnhẢnh trả về nằm trong data[0].b64_json.

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.apivn.dev/v1",
    api_key="<API_KEY>",
    timeout=300,      # mỗi ảnh có thể mất tới vài phút
    max_retries=0,    # không tự gửi lại khi lỗi
)

r = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Một chú cáo trắng ngồi trên mây lúc hoàng hôn",
    size="1024x1792",     # ảnh dọc 9:16
)

with open("anh.bin", "wb") as f:
    f.write(base64.b64decode(r.data[0].b64_json))

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({
  baseURL: "https://api.apivn.dev/v1",
  apiKey: "<API_KEY>",
  timeout: 300000,   // 300 giây
  maxRetries: 0,     // không tự gửi lại khi lỗi
});

const r = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "Một chú cáo trắng ngồi trên mây lúc hoàng hôn",
  size: "1024x1792",   // ảnh dọc 9:16
});

fs.writeFileSync("anh.bin", Buffer.from(r.data[0].b64_json, "base64"));

curl https://api.apivn.dev/v1/images/generations \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A white fox sitting on a cloud at sunset",
    "size": "1024x1792",
    "n": 1
  }'

Tạo ảnh

POST /v1/images/generations, cùng định dạng với API ảnh của OpenAI.

Tham số

Kết quả trả về

Ảnh luôn ở dạng base64 trong data[0].b64_json, không có link tải.

{
  "created": 1763000000,
  "data": [ { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." } ]
}

import base64, io
from PIL import Image

img = Image.open(io.BytesIO(base64.b64decode(r.data[0].b64_json)))
img.convert("RGB").save("anh.jpg", quality=92)   # hoặc img.save("anh.png")

Nền trong suốt

r = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Logo con mèo hoạt hình, nét đơn giản",
    size="1024x1024",
    background="transparent",
)

Tạo nhiều ảnh cùng lúc

Mỗi yêu cầu chỉ ra một ảnh. Muốn nhiều ảnh thì chạy song song, tối đa 5 yêu cầu cùng lúc.

import base64
from concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.apivn.dev/v1", api_key="<API_KEY>",
                timeout=300, max_retries=0)

def make(prompt):
    r = client.images.generate(model="gpt-image-2.5-flare", prompt=prompt, size="1024x1792")
    return base64.b64decode(r.data[0].b64_json)

prompts = ["Một con mèo trên mái nhà", "Một con chó ở bãi biển", "Một chú chim trong rừng"]
with ThreadPoolExecutor(max_workers=5) as pool:
    for i, data in enumerate(pool.map(make, prompts)):
        open(f"anh_{i}.bin", "wb").write(data)

Chữ trong ảnh

Chữ tiếng Việt có dấu hiển thị đúng. Đặt phần chữ trong dấu ngoặc kép trong prompt để giữ nguyên nội dung.

Poster khuyến mãi nền đỏ, chữ trắng lớn ở giữa: "GIẢM GIÁ 50% - MUA 1 TẶNG 1"

Kích thước ảnh

Chỉ nhận các giá trị size dưới đây. Giá trị khác bị từ chối ngay và không tính phí.

Bảng chi tiết

Cần đúng 1080×1920 hoặc 1920×1080

Tạo ảnh ở cỡ gần nhất trong bảng rồi phóng hoặc cắt ở phía bạn. Các cỡ như 1080x1920, 720x1280, 1024x1280, 512x512 bị từ chối.

from PIL import Image
import io, base64

img = Image.open(io.BytesIO(base64.b64decode(r.data[0].b64_json)))   # 1008 x 1792
img = img.resize((1080, 1920), Image.LANCZOS)
img.convert("RGB").save("story_1080x1920.jpg", quality=92)

Chat và đọc ảnh

Gửi ảnh vào chat để hỏi nội dung hoặc đọc chữ trong ảnh. POST /v1/chat/completions.

Xem model được dùng

curl https://api.apivn.dev/v1/models \
  -H "Authorization: Bearer <API_KEY>"

Kết quả liệt kê đúng những model key của bạn gọi được. Dùng tên trong danh sách này cho tham số model của chat.

Gửi ảnh để hỏi

resp = client.chat.completions.create(
    model="<MODEL_CHAT>",   # lấy từ /v1/models
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Mô tả ảnh này bằng tiếng Việt."},
            {"type": "image_url", "image_url": {"url": "https://example.com/anh.png"}},
        ],
    }],
)
print(resp.choices[0].message.content)

import base64

b64 = base64.b64encode(open("anh.png", "rb").read()).decode()

resp = client.chat.completions.create(
    model="<MODEL_CHAT>",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Đọc chữ trong ảnh này."},
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
        ],
    }],
)
print(resp.choices[0].message.content)

Giới hạn và tính năng

Biết trước cái gì làm được và cái gì chưa để khỏi mất công thử.

Đã hỗ trợ

Chưa hỗ trợ trong bản này

Thời gian và số yêu cầu

Quy định sử dụng

• Bạn chịu trách nhiệm về nội dung do mình yêu cầu tạo và cách sử dụng ảnh.
• Không dùng để tạo ảnh giả mạo người thật, nội dung lừa đảo, xâm phạm bản quyền hoặc nội dung trái pháp luật.
• Giữ kín API key. Nghi key bị lộ thì báo ngay để được cấp key mới.

Thử tạo ảnh

Tạo một ảnh thử ngay trên trình duyệt. Mỗi lần bấm tính một ảnh vào hạn mức của key bạn.

Mã tương ứng

Lệnh cURL này tạo đúng ảnh như trên, cập nhật theo các ô phía trên.

Lỗi thường gặp

Triệu chứng, nguyên nhân và cách sửa.

Bảng tra nhanh

Câu hỏi hay gặp

Vẫn không chạy?

1. Gọi thẳng bằng cURL để loại trừ lỗi do mã của bạn:

   curl https://api.apivn.dev/v1/models \
     -H "Authorization: Bearer <API_KEY>"

   Lệnh này chạy mà mã của bạn không chạy thì lỗi nằm ở cấu hình trong mã.
2. Soi lại ba thứ: Base URL có /v1, key dán đủ ký tự, tên model đúng.
3. Liên hệ hỗ trợ: [ĐIỀN LIÊN HỆ HỖ TRỢ]. Gửi ảnh chụp lỗi và 4 ký tự cuối của key, không gửi cả key.