🌐 Webhook API Server

Local REST API server — lets external tools (n8n, Make.com, Zapier, Python, cURL, AI agents...) submit image, video (Veo) and Grok generation requests over HTTP.

7.1 Setup

Step 1: Configure Server

Step 2: Generate API Key

1. Click 🔑 Generate — the app creates a random API key (32-byte URL-safe token)
2. Click 📋 Copy to copy the key to clipboard
3. Add the key to the X-API-Key header for all requests (except /api/health and /api/files/*)

Step 3: Start Server

1. Choose a port → click ▶ Start Server
2. Server runs in the background — does not affect other app features
3. Click ⏹ Stop Server to shut down anytime

7.2 API Endpoints

7.3 Flow Image API

POST /api/image/generate

Image Model Table

7.4 Flow Video API (Veo)

POST /api/video/generate

Video Model Table

Video Modes (mode)

7.5 Grok AI Image/Video API NEW

POST /api/grok/generate

One endpoint for all 4 Grok modes — selected via the mode parameter.

7.6 Meta AI Image/Video API NEW

POST /api/meta/generate

One endpoint for all 4 Meta AI modes (internal backend name "vibes") — selected via the mode parameter. Reference images are passed as named slots (not the reference_images array).

7.7 Reference Images & @tag Binding

Each entry of reference_images is either:

// Format 1: base64 string (data URI or raw base64) — PNG/JPG/WEBP
"reference_images": ["data:image/png;base64,iVBOR..."]

// Format 2: object — with category and/or name
"reference_images": [
  {"data": "data:image/png;base64,...", "category": "subject", "name": "red_car.png"},
  {"data": "data:image/jpeg;base64,...", "name": "house.jpg"}
]

• category (optional): subject / scene / style — accepted but ignored for Flow image models (single generic reference slot)
• name (or filename, optional): the image's original filename → lets you bind it into the prompt with @tag
• Max count: image = 10, grok = 5, video = 3 (Omni Flash components = 7). Extra entries are ignored

Binding images by name with @tag

When a reference image has a name, you point at it inside the prompt with @<keyword> — the same mechanism as the Image / Veo pages in the app.

• Matching: <keyword> is a case-insensitive substring of the filename (without extension). E.g. name: "red_car.png" → @red_car, @car, @red all hit; the first image in order wins
• Scope: works for image (Flow) and video (Veo); Grok does NOT support @tag
• Unmatched tags stay as literal text — they never cause an error

{
  "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 & Status

Successful submission (202 Accepted)

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

Check status: GET /api/status/{task_id}

When 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
}

When 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)"
}

Error code table (error_code)

7.9 Usage Examples

Example 1: Generate image with cURL

# 1. Submit image generation request
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 until completed
curl http://127.0.0.1:8765/api/status/abc12345 -H "X-API-Key: YOUR_API_KEY"

# 3. Download result (no API key needed)
curl -O http://127.0.0.1:8765/api/files/image_001.png

Example 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"}

# Submit
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 until done
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 needs no key
            open(url.split("/")[-1], "wb").write(data)
        break
    if s["status"] == "failed":
        print(f"[{s['error_code']}] {s['error']}")
        break
    time.sleep(4)

Example 3: Video (start image) + Grok (image-to-video)

# Veo — start image + prompt, 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 seconds
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 Request Log

All requests are logged in the Request Log table on the interface — including time, endpoint, status code, task ID, and source IP.