hy-image-v3.5-free là model tạo ảnh thế hệ mới của Hunyuan được Kira AI tích hợp hoàn toàn miễn phí: chất lượng ảnh lên tới 2K, hiểu prompt tiếng Việt tự nhiên, hỗ trợ cả Text-to-Image lẫn Image-to-Image (đưa tối đa 5 ảnh mẫu để biến thể, chỉnh sửa theo ý muốn). API tuân thủ chuẩn OpenAI-compatible nên bạn có thể tích hợp vào bất kỳ ngôn ngữ nào.

Thông tin kết nối

Lấy API Key tại kiraai.vn → mục Developer / API Keys. Lưu ý: đây là model đối tác miễn phí nhưng tài khoản của bạn cần có số dư ví trên 0đ để sử dụng (không bị trừ tiền khi tạo ảnh).

Tham số request

Gọi API bằng cURL

curl -X POST "https://kiraai.vn/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_KIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Một chú cá voi đang bay lơ lửng trên bầu trời Hà Nội lúc hoàng hôn, phong cách điện ảnh",
    "model": "hy-image-v3.5-free",
    "aspect_ratio": "16:9"
  }'

Response trả về — ảnh nằm ở data[0].b64_json dưới dạng chuỗi Base64:

{
  "created": 1790486594,
  "model": "hy-image-v3.5-free",
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...", "mime_type": "image/png" }
  ],
  "description": null
}

Image-to-Image: biến thể ảnh từ ảnh mẫu

Đưa kèm reference_images (chuỗi Base64 thuần của ảnh) để model vẽ lại hoặc biến thể theo ảnh gốc — cực hợp cho việc đổi phong cách, thay nhân vật, thêm chi tiết:

curl -X POST "https://kiraai.vn/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_KIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Thêm nhiều chú cá bay theo đàn phía sau, bầu trời đầy sao",
    "model": "hy-image-v3.5-free",
    "aspect_ratio": "16:9",
    "reference_images": [
      { "data": "BASE64_CUA_ANH_GOC", "mime_type": "image/png" }
    ]
  }'

Tích hợp bằng Code

NodeJS (Fetch)

async function taoAnhKiraAI(prompt, apiKey) {
  const response = await fetch('https://kiraai.vn/api/v1/images/generations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      prompt,
      model: 'hy-image-v3.5-free',
      aspect_ratio: '16:9'
    })
  });

  const data = await response.json();
  if (!response.ok) throw new Error(data.error?.message || 'Tạo ảnh thất bại');

  // Chuyển Base64 thành file ảnh
  const fs = await import('fs');
  fs.writeFileSync('anh-ket-qua.png', Buffer.from(data.data[0].b64_json, 'base64'));
  return 'anh-ket-qua.png';
}

Python (Requests)

import requests, base64

url = "https://kiraai.vn/api/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_KIRA_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "prompt": "Một chú cá voi đang bay trên bầu trời Hà Nội lúc hoàng hôn",
    "model": "hy-image-v3.5-free",
    "aspect_ratio": "16:9"
}

response = requests.post(url, json=payload, headers=headers, timeout=120)
response.raise_for_status()

image_b64 = response.json()["data"][0]["b64_json"]
with open("anh-ket-qua.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

PHP / WordPress

<?php
$response = wp_remote_post( 'https://kiraai.vn/api/v1/images/generations', [
    'headers' => [
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer ' . $api_key,
    ],
    'body'    => wp_json_encode([
        'prompt'       => 'Một chú cá voi đang bay trên bầu trời Hà Nội lúc hoàng hôn',
        'model'        => 'hy-image-v3.5-free',
        'aspect_ratio' => '16:9',
    ]),
    'timeout' => 120,
] );

$data = json_decode( wp_remote_retrieve_body( $response ), true );
$image_base64 = $data['data'][0]['b64_json'] ?? '';
// Lưu file: file_put_contents( $path, base64_decode( $image_base64 ) );
?>

Lưu ý quan trọng khi tích hợp

1. Đặt timeout tối thiểu 120 giây: quá trình tạo ảnh thường mất 15–40 giây, lúc hệ thống đông có thể lâu hơn. HTTP client của bạn cần chờ đủ lâu để không bỏ lỡ kết quả.
2. Ảnh trả về dạng Base64: hãy giải mã và lưu thành file vật lý (hoặc upload lên CDN/S3) trước khi hiển thị — đừng nhúng chuỗi Base64 trực tiếp vào HTML vì sẽ làm trang rất nặng.
3. Prompt tiếng Việt hoạt động tốt: bạn có thể mô tả bằng tiếng Việt tự nhiên, model hiểu và render chuẩn ý tưởng.
4. Image-to-Image dùng Base64 thuần: khi gửi reference_images, truyền chuỗi Base64 của ảnh (không kèm tiền tố data:image/...;base64,). Ảnh mẫu quá lớn (>2MB) nên được nén nhỏ lại trước khi gửi.
5. Bảo mật API Key: luôn gọi API từ backend/server của bạn, tuyệt đối không nhúng API Key vào code phía client.