🌐 Webhook API Server

Máy chủ REST API cục bộ — cho phép công cụ bên ngoài (n8n, Make.com, Zapier, Python, cURL, AI agent...) gửi yêu cầu tạo ảnh, video (Veo) và Grok tự động qua HTTP.

7.1 Thiết Lập

Bước 1: Cấu hình Server

Bước 2: Tạo API Key

1. Nhấn 🔑 Generate — hệ thống tạo API key ngẫu nhiên (token URL-safe 32 byte)
2. Nhấn 📋 Copy để sao chép key vào clipboard
3. Thêm key vào header X-API-Key cho mọi request (trừ /api/health và /api/files/*)

Bước 3: Bật Server

1. Chọn port → Nhấn ▶ Start Server
2. Server chạy nền — không ảnh hưởng đến các tính năng khác của app
3. Nhấn ⏹ Stop Server để tắt bất kỳ lúc nào

7.2 Danh Sách API Endpoints

7.3 Tạo Ảnh Flow Qua API

POST /api/image/generate

Bảng Model Ảnh

7.4 Tạo Video Flow Qua API (Veo)

POST /api/video/generate

Bảng Model Video

Chế Độ Video (mode)

7.5 Tạo Ảnh/Video Grok AI Qua API MỚI

POST /api/grok/generate

Một endpoint cho cả 4 chế độ Grok — phân biệt bằng tham số mode.

7.6 Tạo Ảnh/Video Meta AI Qua API MỚI

POST /api/meta/generate

Một endpoint cho cả 4 chế độ Meta AI (backend nội bộ tên "vibes") — phân biệt bằng tham số mode. Ảnh tham chiếu truyền theo slot có tên (không dùng mảng reference_images).

7.7 Ảnh Tham Chiếu & Gắn Ảnh Bằng @tag

Mỗi phần tử trong reference_images có thể là:

// Dạng 1: Chuỗi base64 (data URI hoặc base64 thô) — PNG/JPG/WEBP
"reference_images": ["data:image/png;base64,iVBOR..."]

// Dạng 2: Object — kèm category và/hoặc name
"reference_images": [
  {"data": "data:image/png;base64,...", "category": "subject", "name": "red_car.png"},
  {"data": "data:image/jpeg;base64,...", "name": "house.jpg"}
]

• category (tùy chọn): subject / scene / style — được chấp nhận nhưng bỏ qua với model Flow (chỉ dùng 1 slot ảnh chung)
• name (hoặc filename, tùy chọn): tên file gốc của ảnh → cho phép gắn ảnh vào prompt bằng @tag
• Giới hạn số ảnh: image = 10, grok = 5, video = 3 (Omni Flash components = 7). Phần dư bị bỏ qua

Gắn ảnh theo tên với @tag

Khi ảnh có name, bạn trỏ tới nó ngay trong prompt bằng @<từ khóa> — đúng cơ chế như trang Tạo Ảnh / Veo trong app.

• So khớp: <từ khóa> là chuỗi con (không phân biệt hoa thường) của tên file (bỏ đuôi). VD name: "red_car.png" → @red_car, @car, @red đều trúng; ảnh xuất hiện đầu tiên trong danh sách thắng
• Phạm vi: dùng cho ảnh (Flow) và video (Veo); Grok KHÔNG hỗ trợ @tag
• Tag không khớp giữ nguyên dạng văn bản — không gây lỗi

{
  "prompt": "a @red_car parked next to a @house at night",
  "reference_images": [
    {"data": "data:image/png;base64,...", "name": "red_car.png"},
    {"data": "data:image/jpeg;base64,...", "name": "house.jpg"}
  ]
}

7.8 Response & Trạng Thái

Khi gửi request thành công (202 Accepted)

{
  "task_id": "abc12345",
  "status": "pending",
  "message": "Image task queued for processing",
  "poll_url": "/api/status/abc12345"
}

Kiểm tra trạng thái: GET /api/status/{task_id}

Khi hoàn thành (completed)

{
  "task_id": "abc12345",
  "type": "image",
  "status": "completed",
  "prompt": "a cat ...",
  "created_at": 1707782400.0,
  "results": ["http://127.0.0.1:8765/api/files/image_001.png"],
  "completed_at": 1707782460.0
}

Khi thất bại (failed)

{
  "task_id": "abc12345",
  "type": "image",
  "status": "failed",
  "error_code": 429,
  "error": "Daily image quota exhausted (user@gmail.com)",
  "error_detail": "429: Daily image quota exhausted (user@gmail.com)"
}

Bảng mã lỗi (error_code)

7.9 Ví Dụ Sử Dụng

Ví dụ 1: Tạo ảnh bằng cURL

# 1. Gửi yêu cầu tạo ảnh
curl -X POST http://127.0.0.1:8765/api/image/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"prompt": "a golden retriever on a beach at sunset", "model": "nano_banana_2", "aspect_ratio": "16:9"}'

# → {"task_id":"abc12345","status":"pending","poll_url":"/api/status/abc12345"}

# 2. Poll cho đến khi completed
curl http://127.0.0.1:8765/api/status/abc12345 -H "X-API-Key: YOUR_API_KEY"

# 3. Tải ảnh kết quả (không cần API key)
curl -O http://127.0.0.1:8765/api/files/image_001.png

Ví dụ 2: Python (submit → poll → download)

import time, requests

BASE = "http://127.0.0.1:8765"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

# Gửi yêu cầu
resp = requests.post(f"{BASE}/api/image/generate", json={
    "prompt": "cyberpunk city at night, neon lights",
    "model": "nano_banana_pro",
    "aspect_ratio": "16:9",
    "upscale": ["2K"]
}, headers=H)
task_id = resp.json()["task_id"]

# Poll cho đến khi xong
while True:
    s = requests.get(f"{BASE}/api/status/{task_id}", headers=H).json()
    if s["status"] == "completed":
        for url in s["results"]:
            data = requests.get(url).content   # /api/files không cần key
            open(url.split("/")[-1], "wb").write(data)
        break
    if s["status"] == "failed":
        print(f"[{s['error_code']}] {s['error']}")
        break
    time.sleep(4)

Ví dụ 3: Video (ảnh đầu) + Grok (image-to-video)

# Veo — ảnh đầu + prompt, xuất 1080p
curl -X POST http://127.0.0.1:8765/api/video/generate \
  -H "Content-Type: application/json" -H "X-API-Key: YOUR_API_KEY" \
  -d '{"prompt":"flowing water, cinematic","mode":"start_image","reference_images":["data:image/png;base64,..."],"resolution":["1080p"]}'

# Grok — image-to-video, 720p, 6 giây
curl -X POST http://127.0.0.1:8765/api/grok/generate \
  -H "Content-Type: application/json" -H "X-API-Key: YOUR_API_KEY" \
  -d '{"prompt":"make it rain over the city","mode":"i2v","aspect_ratio":"16:9","resolution":"720p","reference_images":["data:image/png;base64,..."]}'

7.10 Nhật Ký Yêu Cầu

Mọi request đều được ghi lại trong bảng Request Log trên giao diện — gồm thời gian, endpoint, mã trạng thái, task ID và IP nguồn.