Tài liệu hướng dẫn tích hợp API

1. Giới thiệu nền tảng Kira AI

Kira AI là cổng kết nối API tập trung, bảo mật và có hiệu năng cao, kết nối trực tiếp đến các dòng mô hình ngôn ngữ lớn (LLM) hàng đầu hiện nay. Nền tảng được tối ưu hóa chi phí vượt trội, cung cấp giải pháp kết nối White-Label thuần khiết giúp nhà phát triển dễ dàng tích hợp trí tuệ nhân tạo đa dạng vào ứng dụng của mình mà không bị giới hạn bởi một nhà cung cấp đơn lẻ.

Hệ thống hỗ trợ 2 phương thức giao tiếp chính: Trò chuyện trực tuyến (Web Client) trực tiếp trên trình duyệt và Cổng API kết nối ngoài tương thích hoàn toàn 100% với định dạng chuẩn OpenAI, giúp dễ dàng tích hợp và mở rộng các mô hình AI thông minh vào các phần mềm viết sẵn.

2. Quản lý API key & xác thực

Để tích hợp Kira AI vào các công cụ như Cursor, LibreChat, NextChat, OpenWebUI, Obsidian,... bạn cần tạo API Key tại tab Quản lý API key trong màn hình Console của tài khoản.

3. Hướng dẫn sử dụng chat API

API chat hỗ trợ trò chuyện, phân tích dữ liệu, sinh code tự động. Bạn có thể sử dụng các thư viện SDK OpenAI của bất cứ ngôn ngữ nào bằng cách đổi baseURL.

• Kira Mini 1.0 (kira-mini-1.0): Mô hình AI miễn phí, đa năng, phù hợp cho hội thoại hàng ngày. Không tốn lượt token.
• Kira 3.5 Pro (kira-3.5-pro): Kira 3.5 Pro nhắm thẳng vào tốc độ phản hồi cực nhanh, khả năng lập trình chuyên sâu.
• Kira 3.5 Flash (kira-3.5-flash): Mô hình mặc định, cực kỳ đa năng, tốc độ phản hồi nhanh như chớp và thông minh vượt trội.
• Kira 2.5 Pro (kira-2.5-pro): Dòng mô hình pro, phù hợp cho hầu hết mọi nhu cầu lập trình, xử lý văn bản phức tạp.
• Kira 2.5 Flash (kira-2.5-flash): Dòng mô hình ổn định lâu dài, phù hợp cho hầu hết mọi nhu cầu xử lý thông tin thông thường và tạo giọng nói.

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://kiraai.vn/api/v1", 
  apiKey: "YOUR_KIRA_API_KEY" 
});

const completion = await openai.chat.completions.create({
  model: "kira-3.5-flash",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Xin chào Kira AI!" }
  ]
});

console.log(completion.choices[0].message.content);

4. Gửi hình ảnh cho model phân tích (Vision)

Các model hỗ trợ vision cho phép bạn gửi hình ảnh kèm theo tin nhắn để AI phân tích, mô tả hoặc trích xuất thông tin. Kira AI hỗ trợ đầy đủ định dạng image_url theo chuẩn OpenAI, bao gồm cả URL công khai và base64.

• URL công khai: Gửi trực tiếp link ảnh từ internet (JPG, PNG, GIF, WebP).
• Base64: Gửi ảnh dạng data:image/jpeg;base64,... cho ảnh upload từ thiết bị.
• Nhiều ảnh: Bạn có thể gửi nhiều ảnh cùng lúc trong một tin nhắn.

const completion = await openai.chat.completions.create({
  model: "kira-3.5-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Mô tả chi tiết hình ảnh này" },
        {
          type: "image_url",
          image_url: {
            url: "https://example.com/photo.jpg"
          }
        }
      ]
    }
  ]
});

console.log(completion.choices[0].message.content);

import fs from "fs";

// Đọc file ảnh và chuyển sang base64
const imageBuffer = fs.readFileSync("./photo.jpg");
const base64Image = imageBuffer.toString("base64");

const completion = await openai.chat.completions.create({
  model: "kira-3.5-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Ảnh này chụp gì?" },
        {
          type: "image_url",
          image_url: {
            url: `data:image/jpeg;base64,${base64Image}`
          }
        }
      ]
    }
  ]
});

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://kiraai.vn/api/v1",
    api_key="YOUR_KIRA_API_KEY"
)

# Cách 1: Gửi URL ảnh
response = client.chat.completions.create(
    model="kira-3.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Mô tả hình ảnh này"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/photo.jpg"
                    }
                }
            ]
        }
    ]
)

print(response.choices[0].message.content)

5. Hướng dẫn sử dụng image generation API

Tạo hình ảnh nghệ thuật chất lượng cao từ mô tả văn bản thông qua endpoint /images/generations.

curl -X POST https://kiraai.vn/api/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KIRA_API_KEY" \
  -d '{
    "model": "kira-3.0-image",
    "prompt": "A beautiful cyber-punk city in rain, neon light reflections, high resolution",
    "aspect_ratio": "16:9"
  }'

6. Hướng dẫn sử dụng text to speech API (TTS)

API Text-to-Speech (TTS) của Kira AI cho phép bạn chuyển đổi văn bản viết thành các tệp âm thanh giọng nói tự nhiên, chất lượng cao. API tương thích hoàn toàn với định dạng chuẩn OpenAI tại endpoint /audio/speech.

curl -X POST https://kiraai.vn/api/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KIRA_API_KEY" \
  -d '{
    "model": "kira-3.0-flash-tts",
    "input": "Chào mừng bạn đến với hệ sinh thái trí tuệ nhân tạo Kira AI.",
    "voice": "alloy"
  }' --output output.mp3

import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://kiraai.vn/api/v1",
  apiKey: "YOUR_KIRA_API_KEY"
});

const mp3 = await openai.audio.speech.create({
  model: "kira-3.0-flash-tts",
  voice: "alloy",
  input: "Chào mừng bạn đến với hệ sinh thái trí tuệ nhân tạo Kira AI."
});

const buffer = Buffer.from(await mp3.arrayBuffer());
await fs.promises.writeFile("output.mp3", buffer);

7. Hướng dẫn sử dụng video generation API

Kira AI hỗ trợ tạo video bằng trí tuệ nhân tạo thông qua các mô hình:

• Kira 3.0 Video (kira-3.0-video): Dựng chuyển động video độ phân giải cao và chân thực từ mô tả văn bản (LRO).
• Kira 3.0 Video Flash (kira-3.0-video-flash): Mô hình video tiên tiến, có khả năng tạo video dài 10s và chỉnh sửa video tiên tiến.

Quá trình xử lý video diễn ra bất đồng bộ thông qua mô hình Operation:

8. Hướng dẫn cấu hình Kira AI cho Codex (CLI & Desktop app)

Codex (bao gồm Codex CLI và Codex Desktop app) là trợ lý lập trình chuyên sâu của OpenAI, cho phép đọc hiểu toàn bộ workspace, phân tích codebase, tự động sinh code, tạo và chỉnh sửa file, cũng như thực thi lệnh shell trực tiếp.

Kira AI cung cấp cổng kết nối chuẩn OpenAI Responses API (endpoint /api/v1/responses), hỗ trợ đầy đủ Server-Sent Events (SSE) streaming và cơ chế tool calling native/custom, giúp Codex hoạt động mượt mà và tự động thao tác file chính xác 100%.

# Khai báo nhà cung cấp mặc định (viết thường toàn bộ: "kiraai")
model_provider = "kiraai"
model = "gpt-5.6-sol" # Khuyên dùng: gpt-5.6-sol, gpt-5.6-luna hoặc gpt-oss-120b
model_reasoning_effort = "medium"
approval_policy = "never"

# Định nghĩa provider Kira AI kết nối qua Responses API
[model_providers.kiraai]
name = "kiraai"
base_url = "https://kiraai.vn/api/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"

# Cấp quyền tin cậy cho thư mục dự án (để Codex tự động tạo file và chạy lệnh shell)
[projects."/duong/dan/den/thu/muc/du/an"]
trust_level = "trusted"

# Thêm biến môi trường vào ~/.zshrc (hoặc ~/.bashrc)
echo 'export OPENAI_API_KEY="kira_api_key_cua_ban"' >> ~/.zshrc
source ~/.zshrc

// Mở tệp ~/.codex/auth.json và dán nội dung:
{
  "OPENAI_API_KEY": "kira_api_key_cua_ban"
}

9. Hướng dẫn User Management API (quản trị tài khoản)

Bộ RESTful Management API v1 cho phép lập trình viên tự động hóa việc kiểm tra số dư VND/Token, tạo & quản lý khóa API Key, và tra cứu chi tiết Lịch sử sử dụng tiêu thụ token một cách nhanh chóng.

curl -X GET https://kiraai.vn/api/v1/user/profile \
  -H "Authorization: Bearer YOUR_API_KEY_HOAC_JWT"

const res = await fetch('https://kiraai.vn/api/v1/user/usage/logs?page=1&limit=20', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await res.json();
console.log(data.logs); // Mảng chi tiết: timestamp, model, prompt_tokens, completion_tokens, tokens_used, cost_vnd...

curl -X POST https://kiraai.vn/api/v1/user/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "App Mobile Key"}'

10. Tài liệu API bổ trợ (mô hình & giọng đọc)

Kira AI cung cấp các API bổ trợ hữu ích giúp bạn truy vấn động Danh sách mô hình đang hoạt động và danh sách giọng đọc của hệ thống Text-to-Speech (TTS).

curl -X GET https://kiraai.vn/api/v1/models \
  -H "Authorization: Bearer YOUR_KIRA_API_KEY"

curl -X GET https://kiraai.vn/api/v1/audio/voices