Usage Guide

Integrate VietAI Gateway into your applications and IDEs

🔗 Enter your domain (automatically filled in all examples below):

Quick Start

VietAI Gateway is 100% compatible with OpenAI API. Just change the base_url and api_key.

1
Sign Up
Create a free account
2
Get API Key
Dashboard → API Keys
3
Call API
Use OpenAI SDK or cURL
Connection Info:
Base URL: https://vertex-key.com/api/v1
API Key: vai-xxxxxxxxxx (get from Dashboard)

Configure Claude Code (CLI)

Claude Code is Anthropic's official CLI tool for coding with Claude. Connect it to VietAI Gateway to use all available models.

ℹ️ Lưu ý: Claude Code SDK tự động thêm /v1/messages vào base URL. Dùng https://vertex-key.com/api (không có /v1) để tránh bị trùng path. Gateway hỗ trợ cả hai format nhưng khuyến nghị dùng format chuẩn.

Method 1: Environment Variables (Recommended)

Set these environment variables before running claude:

bash
# Linux / macOS
export ANTHROPIC_BASE_URL=https://vertex-key.com/api
export ANTHROPIC_API_KEY=vai-your-api-key-here

# Windows (PowerShell)
$env:ANTHROPIC_BASE_URL="https://vertex-key.com/api"
$env:ANTHROPIC_API_KEY="vai-your-api-key-here"

# Then run Claude Code as normal
claude

Method 2: Use with --model flag

Specify model directly when launching:

bash
# Use specific model tier
claude --model omega/claude-opus-4-6
claude --model flash/claude-opus-4-6
claude --model flash/claude-sonnet-4-6
claude --model omega/claude-sonnet-4-6

Method 3: Persistent config (~/.claude/settings.json)

Add to your Claude Code settings file for permanent configuration:

json (~/.claude/settings.json)
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://vertex-key.com/api",
    "ANTHROPIC_API_KEY": "vai-your-api-key-here"
  }
}
💡 Recommended models for Claude Code:
omega/claude-opus-4-6 — Best quality, tool use support
omega/claude-sonnet-4-6 — Tool use + fast
flash/claude-opus-4-6 — Fast response, 1M context
flash/claude-sonnet-4-6 — Fastest, budget-friendly
⚠️ Note: Use vai-xxx API key (from Dashboard). Model IDs use dashes: claude-opus-4-6 (not dots). Cả https://vertex-key.com/apihttps://vertex-key.com/api/v1 đều hoạt động.

Configure Cursor IDE

Add VietAI Gateway as an AI provider in Cursor IDE.

Step 1: Open Cursor Settings

Go to Cursor Settings → Models → OpenAI API Key

Cursor Settings
Base URL:  https://vertex-key.com/api/v1
API Key:   vai-your-api-key-here

Step 2: Add Models

In the model list, click + Add Model and enter these model IDs:

Model IDs to add
omega/claude-opus-4-6        (best quality, tool use)
omega/claude-sonnet-4-6      (fast + tool use)
flash/claude-opus-4-6        (fast response)
flash/claude-sonnet-4-6      (fastest Claude)
pro/gpt-5.2                  (best GPT, reasoning)
pro/gpt-5.3-codex-xhigh     (best for code)
gem/gemini-3.1-pro-preview   (Gemini latest)
💡 Tip: For Cursor, use omega/ models (tool use support) or flash/ models (fastest response). Both work great for code completion and chat.
⚠️ Note: Use vai-xxx API key (from Dashboard), not the original sk-xxx key. Model IDs accept both formats: claude-opus-4-6 or claude-opus-4.6.

Configure Continue.dev (VS Code / JetBrains)

Open file ~/.continue/config.json and add:

json (~/.continue/config.json)
{
  "models": [
    {
      "title": "Claude Opus 4.6 (Omega)",
      "provider": "openai",
      "model": "omega/claude-opus-4-6",
      "apiBase": "https://vertex-key.com/api/v1",
      "apiKey": "vai-your-api-key-here"
    },
    {
      "title": "Claude Sonnet 4.6 (Flash)",
      "provider": "openai",
      "model": "flash/claude-sonnet-4-6",
      "apiBase": "https://vertex-key.com/api/v1",
      "apiKey": "vai-your-api-key-here"
    },
    {
      "title": "GPT-5.2 (Pro)",
      "provider": "openai",
      "model": "pro/gpt-5.2",
      "apiBase": "https://vertex-key.com/api/v1",
      "apiKey": "vai-your-api-key-here"
    },
    {
      "title": "GPT-5.3 Codex (Pro)",
      "provider": "openai",
      "model": "pro/gpt-5.3-codex-xhigh",
      "apiBase": "https://vertex-key.com/api/v1",
      "apiKey": "vai-your-api-key-here"
    }
  ],
  "tabAutocompleteModel": {
    "title": "Claude Haiku 4.5 (Fast)",
    "provider": "openai",
    "model": "lite/claude-haiku-4-5",
    "apiBase": "https://vertex-key.com/api/v1",
    "apiKey": "vai-your-api-key-here"
  }
}
💡 Tip: Use lite/claude-haiku-4-5 for tab autocomplete (fast + cheap). Use omega/ or pro/ models for chat.

Configure Cline / Roo Code

In Cline/Roo Code settings, select API Provider: OpenAI Compatible

Cline / Roo Code Settings
API Provider:  OpenAI Compatible
Base URL:      https://vertex-key.com/api/v1
API Key:       vai-your-api-key-here
Model ID:      omega/claude-opus-4-6
💡 Recommended models for Cline / Roo Code:
omega/claude-opus-4-6 — Best quality, tool use support
omega/claude-sonnet-4-6 — Fast + tool use
pro/gpt-5.3-codex-xhigh — Best GPT for code
flash/claude-opus-4-6 — Fast response, 1M context
flash/claude-sonnet-4-6 — Fastest, budget-friendly
⚠️ Note: Cline/Roo Code uses tool calling heavily. Use omega/ tier models for best tool use compatibility.

Configure OpenClaw

OpenClaw is an AI agent framework. Configure it to use VietAI Gateway models.

Add this configuration to your OpenClaw config file:

json (OpenClaw config)
{
  "models": {
    "providers": {
      "vertex-key": {
        "baseUrl": "https://vertex-key.com/api/v1",
        "apiKey": "vai-your-api-key-here",
        "api": "openai-completions",
        "models": [
          {
            "id": "omega/claude-opus-4-6",
            "name": "Claude Opus 4.6 (Omega)",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 1000000,
            "maxTokens": 128000
          },
          {
            "id": "flash/claude-opus-4-6",
            "name": "Claude Opus 4.6 (Flash)",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 1000000,
            "maxTokens": 128000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "vertex-key/omega/claude-opus-4-6"
      }
    }
  }
}
💡 Tip: Use flash/ models (fast) for OpenClaw agents. Use omega/ if you need tool use support.
📖 Full Guide: See our complete OpenClaw integration guide for detailed instructions and best practices.

Python (OpenAI SDK)

bash
pip install openai
python
from openai import OpenAI

client = OpenAI(
    api_key="vai-your-api-key-here",
    base_url="https://vertex-key.com/api/v1"
)

# Chat
response = client.chat.completions.create(
    model="omega/claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": "You are a smart AI assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    temperature=0.7,
    max_tokens=1024
)
print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="pro/gpt-5.2",
    messages=[{"role": "user", "content": "Write a poem about Hanoi"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

# Vision
response = client.chat.completions.create(
    model="omega/claude-opus-4-6",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image"},
            {"type": "image_url", "image_url": {"url": "https://example.com/img.jpg"}}
        ]
    }]
)

Node.js / TypeScript

typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "vai-your-api-key-here",
  baseURL: "https://vertex-key.com/api/v1",
});

const response = await client.chat.completions.create({
  model: "omega/claude-opus-4-6",
  messages: [{ role: "user", content: "Hello!" }],
});

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

cURL

bash
curl https://vertex-key.com/api/v1/chat/completions \
  -H "Authorization: Bearer vai-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omega/claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello!"}],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

🎨 Image Generation

Generate images using OpenAI-compatible endpoint. Supports Gemini 3.1 (1K/2K/4K), Gemini 2.5 Flash, Nano Banana 2, GPT Image, Sora Image, and more.

📌 MAX models (max/): Ổn định, giá tốt — bltcy + PoloAI.

Available Image Models

Model IDResolutionPrice
gemini-image-1k1408×768 (1K)$0.36/req
gemini-image-2k2816×1536 (2K)$0.45/req
gemini-image-4k5632×3072 (4K)$0.50/req
gemini-2.5-flash-image1024×1024$0.25/req
gpt-image-1.51024×1024$0.36/req
max/gemini-3.1-image-1k1408×768 (1K) 🔥$0.49/req
max/gemini-3.1-image-2k2816×1536 (2K) 🔥$0.65/req
max/gemini-3.1-image-4k5632×3072 (4K) 🔥$0.81/req
max/gemini-2.5-flash-image1024×1024 🔥$0.32/req
max/gemini-3.1-image-1k-p1408×768 (1K) 🔥$0.49/req
max/gemini-3.1-image-2k-p2816×1536 (2K) 🔥$0.65/req
max/gemini-3.1-image-4k-p5632×3072 (4K) 🔥$0.81/req
max/nano-banana-2-1k1408×768 (1K) 🔥$0.65/req
max/nano-banana-2-2k2816×1536 (2K) 🔥$0.81/req
max/nano-banana-2-4k5632×3072 (4K) 🔥$0.97/req
max/gpt-image-1.51024×1024 🔥$0.49/req
max/gpt-image-11024×1024 🔥$0.49/req
max/sora-image1024×1024 🔥$0.49/req
max/sora-image-vip1024×1024 🔥$0.49/req
max/gpt-4o-image1024×1024 🔥$0.49/req

Python — OpenAI SDK

python
from openai import OpenAI

client = OpenAI(
    api_key="vai-your-api-key-here",
    base_url="https://vertex-key.com/api/v1"
)

# Generate image
response = client.images.generate(
    model="gemini-image-1k",          # or max/gemini-3.1-image-4k
    prompt="A cute cat wearing a tiny hat, photorealistic",
    n=1,
    size="1024x1024"
)

# Get image URL or base64
image_url = response.data[0].url
print(f"Image URL: {image_url}")

# If response contains base64
if response.data[0].b64_json:
    import base64
    img_bytes = base64.b64decode(response.data[0].b64_json)
    with open("output.png", "wb") as f:
        f.write(img_bytes)

cURL

bash
curl https://vertex-key.com/api/v1/images/generations \
  -H "Authorization: Bearer vai-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "max/gemini-3.1-image-4k",
    "prompt": "Mountain landscape at sunset, photorealistic",
    "n": 1,
    "size": "1024x1024"
  }'

Node.js

typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "vai-your-api-key-here",
  baseURL: "https://vertex-key.com/api/v1",
});

const response = await client.images.generate({
  model: "max/gemini-3.1-image-1k",
  prompt: "A futuristic cityscape at night",
  n: 1,
  size: "1024x1024",
});

console.log("Image URL:", response.data[0].url);
💡 Tips:
• Model gemini-image-* có Auto Failover — tự động chuyển provider khi lỗi
• Enterprise models (max/) — ổn định hơn, giá cao hơn
• Response trả url hoặc b64_json tùy model
• Thời gian: 1K ~20-40s, 2K ~40-60s, 4K ~60-200s

🎬 Video Generation

Generate videos using AI models. Supports Grok Video 3, Veo 3.1 (3 mức giá), and Image-to-Video.

Available Video Models

Model IDDurationResolutionSpeedPrice
imy/grok-video-36s720p$0.36/video
imy/grok-video-3-10s10s720p$0.46/video
imy/grok-video-3-15s15s720p$0.66/video
imy/veo_3_1-fast-slow5s720p🐢 Chậm$0.90/video
imy/veo_3_1-fast-medium5s720p⚡ Nhanh$1.65/video
imy/veo_3_1-fast-premium5s720p🚀 Cao$2.25/video
imy/veo_3_1-fast-4K-slow5s4K🐢 Chậm$1.65/video
imy/veo_3_1-fast-4K-medium5s4K⚡ Nhanh$2.25/video
imy/veo_3_1-fast-4K-premium5s4K🚀 Cao$3.00/video
max/veo-3.1-fast8s 🏢720pEnterprise$1.35/video
max/veo-3.18s 🏢720p (HQ)Enterprise$1.80/video
💡 Veo 3 mức giá:
Chậm — giá rẻ nhất, server đông người
Nhanh — cân bằng giá/tốc độ
Cao — server ít người, nhanh nhất, không watermark
ℹ️ Video generation là async: Gửi request → nhận task_id → poll status cho đến khi hoàn thành. Thời gian render: Grok ~60-120s, Veo 3.1 ~80-390s.

Python — Tạo video (Text-to-Video)

python
import requests
import time

BASE = "https://vertex-key.com/api/v1"
HEADERS = {
    "Authorization": "Bearer vai-your-api-key-here",
    "Content-Type": "application/json"
}

# Step 1: Create video task
resp = requests.post(f"{BASE}/video/create", headers=HEADERS, json={
    "model": "imy/veo_3_1-fast-medium",   # or max/veo-3.1-fast
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5
})
task = resp.json()
task_id = task["id"]
print(f"Task created: {task_id}")

# Step 2: Poll until complete
while True:
    status = requests.get(
        f"{BASE}/videos/{task_id}",
        headers=HEADERS
    ).json()
    
    print(f"Status: {status['status']} {status.get('progress', '')}%")
    
    if status["status"] == "completed":
        video_url = status["video_url"]
        print(f"✅ Video ready: {video_url}")
        break
    elif status["status"] == "failed":
        print(f"❌ Failed: {status.get('error', 'unknown')}")
        break
    
    time.sleep(10)  # Poll every 10 seconds

🖼️ Image-to-Video — Gửi ảnh + prompt → Video

MỚI: Veo 3.1 hỗ trợ Image-to-Video! Gửi ảnh đầu vào + prompt mô tả chuyển động → Veo tạo video từ ảnh. Format chuẩn OpenAI multimodal (image_url base64).
python
import requests, base64, time

BASE = "https://vertex-key.com/api/v1"
HEADERS = {"Authorization": "Bearer vai-your-api-key-here", "Content-Type": "application/json"}

# Read image → base64
with open("input-car.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

# Step 1: Create video from image
resp = requests.post(f"{BASE}/video/create", headers=HEADERS, json={
    "model": "max/veo-3.1-fast",      # or imy/veo_3_1-fast-medium
    "messages": [{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
            {"type": "text", "text": "Generate a video: car driving into the sunset, cinematic"}
        ]
    }]
})
task_id = resp.json()["id"]
print(f"Task: {task_id}")

# Step 2: Poll (same as text-to-video)
for i in range(60):
    time.sleep(10)
    data = requests.get(f"{BASE}/videos/{task_id}", headers=HEADERS).json()
    print(f"Poll #{i+1}: {data.get('status','')} {data.get('progress',0)}%")
    if data["status"] == "completed":
        print(f"✅ Video: {data['video_url']}")
        break
    if data["status"] == "failed":
        print(f"❌ {data.get('error','')}")
        break

cURL — Tạo video

bash
# Step 1: Create task
curl https://vertex-key.com/api/v1/video/create \
  -H "Authorization: Bearer vai-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imy/veo_3_1-fast-medium",
    "prompt": "Cinematic drone shot over rice terraces at golden hour",
    "duration": 5
  }'
# Response: {"id": "veo:abc123..."}

# Step 2: Poll status (repeat until completed)
curl https://vertex-key.com/api/v1/videos/veo:abc123... \
  -H "Authorization: Bearer vai-your-api-key-here"
# Response: {"status": "completed", "video_url": "https://...mp4"}

Node.js — Tạo video

typescript
const BASE = "https://vertex-key.com/api/v1";
const HEADERS = {
  "Authorization": "Bearer vai-your-api-key-here",
  "Content-Type": "application/json"
};

// Step 1: Create task
const resp = await fetch(BASE + "/video/create", {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    model: "imy/veo_3_1-fast-medium",
    prompt: "A golden retriever running on the beach",
    duration: 5
  })
});
const { id: task_id } = await resp.json();
console.log("Task:", task_id);

// Step 2: Poll until done
while (true) {
  await new Promise(r => setTimeout(r, 10000));
  const status = await fetch(
    BASE + "/videos/" + task_id,
    { headers: HEADERS }
  ).then(r => r.json());
  
  console.log("Status:", status.status, status.progress || "");
  if (status.status === "completed") {
    console.log("Video:", status.video_url);
    break;
  }
  if (status.status === "failed") {
    console.error("Failed:", status.error);
    break;
  }
}
💡 Tips:
duration: Grok hỗ trợ 6/10/15s — Veo 3.1 mặc định 5s
• Video trả về URL .mp4 — download trong 24h trước khi hết hạn
Image-to-Video: Gửi ảnh base64 qua field messages (chuẩn OpenAI vision)
• Veo mức "Cao" — server ít người, không watermark

Popular Model IDs

📌 Model Tiers: flash/ = Fast Response | omega/ = Tool Use + Thinking | pro/ = GPT Pro | lite/ = Budget | gem/ = Gemini | xai/ = Grok | max/ = Enterprise 🏢
Model IDNamePriceFeatures
flash/claude-opus-4-6Claude Opus 4.6 ⚡$5.00 / $25.00Fast, Vision, 1M ctx
flash/claude-sonnet-4-6Claude Sonnet 4.6 ⚡$3.00 / $15.00Fast, Vision, 1M ctx
omega/claude-opus-4-6Claude Opus 4.6 🔱$5.00 / $25.00Tool Use, Vision
omega/claude-sonnet-4-6Claude Sonnet 4.6 🔱$3.00 / $15.00Tool Use, Vision
pro/gpt-5.2GPT-5.2 💎$1.75 / $14.00Reasoning, Vision
pro/gpt-5.3-codex-xhighGPT-5.3 Codex Elite 💎$3.00 / $24.00Code, Reasoning
lite/claude-haiku-4-5Claude Haiku 4.5 💡$1.00 / $5.00Fast, Budget
gem/gemini-3.1-pro-previewGemini 3.1 Pro 💎$3.00 / $18.00Reasoning, Latest
xai/grok-4.1Grok 4.1 ⚡$4.50 / $22.50Reasoning, Latest
xai/grok-4-fastGrok 4 Fast ⚡$1.00 / $2.50Fast
gemini-image-1kGemini Image 1K 🎨$0.36/reqImage, 1408×768
max/gemini-3.1-image-1kGemini 3.1 Image 1K 🏢$0.60/reqImage, Enterprise
max/veo-3.1-fastVeo 3.1 Fast 🏢$1.50/reqVideo, Enterprise

💡 Advanced Examples

Function Calling

python
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather information",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }
}]

response = client.chat.completions.create(
    model="omega/claude-opus-4-6",
    messages=[{"role": "user", "content": "What's the weather in Hanoi?"}],
    tools=tools
)

Use environment variables (recommended)

bash (.env)
OPENAI_API_KEY=vai-your-api-key-here
OPENAI_BASE_URL=https://vertex-key.com/api/v1
python
import os
from openai import OpenAI

# Automatically read from env
client = OpenAI()  # No need to pass api_key, base_url

📡 API Endpoints

POST/api/v1/chat/completionsChat Completion
POST/api/v1/completionsText Completion
POST/api/v1/embeddingsEmbedding
POST/api/v1/images/generationsGenerate Image
POST/api/v1/video/createCreate Video Task
GET/api/v1/videos/:task_idPoll Video Status
POST/api/v1/audio/speechText-to-Speech
POST/api/v1/audio/transcriptionsSpeech-to-Text
GET/api/v1/modelsModel List

⚠️ Error Codes

401
Invalid or missing API key
Check API key again (must start with vai-)
402
Insufficient balance
Top up at Dashboard → Top Up
403
Account locked
Contact admin
429
Rate limit
Reduce API call frequency
502
Upstream error
Try again later or change model