REST API Reference v1.0

GenHub AI API Documentation

Generate cinema-grade AI videos, multi-character scenes, and ultra-high resolution imagery through high-speed REST endpoints.

Base URLhttps://gen.ssapp.vn/api/v1

Security

Authentication

Every API request requires an API key passed via the X-API-Key request header.

Example Header

X-API-Key: gen_your_api_key_here

Generating Your API KeysYou can create, label, and revoke API keys anytime in your Dashboard → API Keys. Each key shares your account balance and supports up to 10 concurrent tasks.

3-Step Flow

Quick Start Tutorial

Submit your prompt, poll the status endpoint until ready, and download the full resolution output:

Step 01

1. Submit Task

POST prompt → receive task_id

Step 02

2. Poll Status

GET /video/status/:taskId every 8-10s

Step 03

3. Stream / Download

Access fifeUrl or download MP4 stream

Task Lifecycle States

State	Description	Action Required
pending	Task initialized in system queue	Continue polling
queued	Concurrency limit reached; waiting for worker slot	Auto starts when slot frees
generating / polling	AI neural model actively rendering frames	Poll every 8-10 seconds
completed	Video/image generation finished; download URLs ready	Retrieve videos / images array
failed	Generation error; reason in error field	Credits refunded automatically

Concurrency & Rates

Max Concurrency

10 Tasks

Simultaneous active generating sessions per account.

Pricing Model

Pay-As-You-Go

Only completed tasks consume credits. Failed tasks are refunded.

API Endpoints Reference

POST/video/text-to-video

Text to Video

Generate high quality 8-second video clips from natural language prompt descriptions.

Parameters

Field	Type	Status	Description
prompt	string	Required	Text description of the desired video scene, style, lighting, and movement.
aspect_ratio	string	Optional	"16:9" (landscape) or "9:16" (portrait). Default: "16:9"
count	integer	Optional	Number of video variants to generate (1–4). Default: 1
duration	string	Optional	Duration of output video ("4s", "6s", "8s"). Default: "8s"

Example Request (curl)

curl -X POST https://gen.ssapp.vn/api/v1/video/text-to-video \
  -H "X-API-Key: gen_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic slow-motion drone shot of neon-lit Tokyo in rain",
    "aspect_ratio": "16:9",
    "duration": "8s"
  }'

Sample Response (JSON)

{
  "success": true,
  "data": {
    "task_id": "task_textto_7b9bed6c80ee",
    "type": "text_to_video",
    "status": "session_init",
    "created_at": "2026-03-09T10:22:00.031Z"
  }
}

POST/video/image-to-video

Image to Video

Animate a starting reference image into dynamic video footage following your creative prompt.

Parameters

Field	Type	Status	Description
prompt	string	Required	Action/motion instructions for how to bring the image to life.
image_base64	string	Required	Raw Base64 string of the image (without data:image prefix).
mime_type	string	Optional	"image/jpeg", "image/png", "image/webp". Default: "image/jpeg"
aspect_ratio	string	Optional	"16:9" or "9:16". Default: "9:16"
duration	string	Optional	"4s", "6s", "8s". Default: "8s"

Example Request (curl)

curl -X POST https://gen.ssapp.vn/api/v1/video/image-to-video \
  -H "X-API-Key: gen_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Camera pans right as ocean waves crash softly",
    "image_base64": "<BASE64_STRING>",
    "aspect_ratio": "16:9"
  }'

Sample Response (JSON)

{
  "success": true,
  "data": {
    "task_id": "task_imaget_a1b2c3d4e5f6",
    "type": "image_to_video",
    "status": "session_init",
    "created_at": "2026-03-09T10:25:00.000Z"
  }
}

POST/video/multi-image-to-video

Multi-Image Reference

Provide multiple character or scene reference images with placeholder name tags in the prompt.

Parameters

Field	Type	Status	Description
prompt	string	Required	Prompt referencing image placeholder names (e.g., "Alex handing coffee to Sarah").
images	array	Required	Array of { name: string, image_base64: string, mime_type: string }
aspect_ratio	string	Optional	"16:9" or "9:16". Default: "16:9"

Example Request (curl)

curl -X POST https://gen.ssapp.vn/api/v1/video/multi-image-to-video \
  -H "X-API-Key: gen_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Alex having a conversation with Elena",
    "images": [
      {"name": "Alex", "image_base64": "<B64>", "mime_type": "image/jpeg"},
      {"name": "Elena", "image_base64": "<B64>", "mime_type": "image/jpeg"}
    ]
  }'

Sample Response (JSON)

{
  "success": true,
  "data": {
    "task_id": "task_multii_c3d4e5f6g7h8",
    "status": "session_init"
  }
}

Name matching is case-insensitive. Ensure image names use Latin characters (A-Z, a-z).

POST/video/batch-frame

Batch Frame Transition

Generate continuous video transition interpolating between a specific start frame and end frame.

Parameters

Field	Type	Status	Description
prompt	string	Required	Description of the transition movement between the two frames.
start_image_base64	string	Required	Base64 of the initial frame.
end_image_base64	string	Required	Base64 of the final ending frame.
aspect_ratio	string	Optional	"16:9" or "9:16". Default: "16:9"

Example Request (curl)

curl -X POST https://gen.ssapp.vn/api/v1/video/batch-frame \
  -H "X-API-Key: gen_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Camera zooms past the mountain peak into the clouds",
    "start_image_base64": "<START_B64>",
    "end_image_base64": "<END_B64>"
  }'

Sample Response (JSON)

{
  "success": true,
  "data": {
    "task_id": "task_batchf_e5f6g7h8i9j0",
    "status": "session_init"
  }
}

POST/video/upsample

Upsample Video (1080p)

Upscale completed videos to pristine 1080p crystal clarity via AI upsampling or dedicated FFmpeg GPU nodes.

Parameters

Field	Type	Status	Description
media_generation_id	string	Required	mediaGenerationId returned in completed video response.
aspect_ratio	string	Optional	"16:9" or "9:16". Default: "16:9"
video_url	string	Optional	Direct MP4 URL (fifeUrl). Routes to high-speed dedicated GPU worker cluster.

Example Request (curl)

curl -X POST https://gen.ssapp.vn/api/v1/video/upsample \
  -H "X-API-Key: gen_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "media_generation_id": "CAUSJDQ1OW...",
    "video_url": "https://storage.googleapis.com/..."
  }'

Sample Response (JSON)

{
  "success": true,
  "data": {
    "task_id": "task_upsamp_987654321",
    "status": "session_init"
  }
}

Providing video_url completes upscaling in ~4–8 seconds with permanently accessible URLs.

GET/video/status/:taskId

Poll Task Status

Fetch live real-time status and generated media URLs for video or image generation tasks.

Parameters

Field	Type	Status	Description
taskId	string (path)	Required	The task ID received when submitting generation.

Example Request (curl)

curl https://gen.ssapp.vn/api/v1/video/status/task_textto_7b9bed6c80ee \
  -H "X-API-Key: gen_your_api_key_here"

Sample Response (JSON)

{
  "success": true,
  "data": {
    "task_id": "task_textto_7b9bed6c80ee",
    "status": "completed",
    "completed_at": "2026-03-09T10:25:43.217Z",
    "videos": [
      {
        "sceneId": "f3753407-feb6-4dee-...",
        "fifeUrl": "https://storage.googleapis.com/ai-sandbox-videofx/video/...",
        "servingBaseUri": "https://storage.googleapis.com/...",
        "mediaGenerationId": "CAUSJDQ1OW...",
        "model": "veo_3_1_t2v_fast_ultra_relaxed",
        "seed": 788754185,
        "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
        "status": "MEDIA_GENERATION_STATUS_SUCCESSFUL"
      }
    ],
    "progress": {
      "total": 1,
      "completed": 1
    }
  }
}

Poll interval of 8–10 seconds is optimal. Live status reflects actual AI worker progress.

GET/video/download/:taskId

Download Video Binary

Directly stream and download generated MP4 video binary file without dealing with signed URLs.

Parameters

Field	Type	Status	Description
taskId	string (path)	Required	Completed task ID.
video_index	integer (query)	Optional	Zero-based index if multiple videos generated. Default: 0

Example Request (curl)

curl -o output.mp4 https://gen.ssapp.vn/api/v1/video/download/task_textto_7b9bed6c80ee \
  -H "X-API-Key: gen_your_api_key_here"

Sample Response (JSON)

[Binary video/mp4 stream]

POST/video/cancel/:taskId

Cancel Task

Cancel an active task (pending/generating/polling) to immediately release concurrency slot.

Parameters

Field	Type	Status	Description
taskId	string (path)	Required	Task ID to terminate.

Example Request (curl)

curl -X POST https://gen.ssapp.vn/api/v1/video/cancel/task_textto_7b9bed6c80ee \
  -H "X-API-Key: gen_your_api_key_here"

Sample Response (JSON)

{
  "success": true,
  "data": {
    "task_id": "task_textto_7b9bed6c80ee",
    "status": "failed",
    "error": "Cancelled by user"
  }
}

POST/video/cancel-all

Cancel All Tasks

Emergency reset to cancel all in-flight tasks and free up all concurrency slots immediately.

Example Request (curl)

curl -X POST https://gen.ssapp.vn/api/v1/video/cancel-all \
  -H "X-API-Key: gen_your_api_key_here"

Sample Response (JSON)

{
  "success": true,
  "data": {
    "cancelled_count": 3,
    "tasks": [
      "task_textto_1",
      "task_imaget_2",
      "task_multii_3"
    ]
  }
}

POST/image/banana/generate

Banana Image Generation

Generate 1–8 ultra-realistic AI images using Banana Pro/2/Lite models with multi-reference matching.

Parameters

Field	Type	Status	Description
prompt	string	Required	Detailed visual prompt.
num_images	integer	Optional	Number of images (1–8). Default: 1
aspect_ratio	string	Optional	"16:9", "9:16", "1:1", "4:3", "3:4". Default: "16:9"
model_key	string	Optional	"banana-pro" (Pro), "banana-2" (Standard), "banana-lite" (Fast). Default: "banana-pro"
reference_images	array	Optional	Array of { name: string, image_base64: string, mime_type: string }
use_all_ref_images	boolean	Optional	When true, applies all reference images regardless of names in prompt. Default: false

Example Request (curl)

curl -X POST https://gen.ssapp.vn/api/v1/image/banana/generate \
  -H "X-API-Key: gen_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A neon cybernetic samurai in cherry blossom rain",
    "num_images": 2,
    "aspect_ratio": "16:9",
    "model_key": "banana-pro"
  }'

Sample Response (JSON)

{
  "success": true,
  "data": {
    "task_id": "img_banana_1786721666798",
    "status": "pending"
  }
}

Poll /video/status/:taskId to retrieve the completed signed image URLs.

POST/image/banana/upscale

Banana Image Upscale

Upscale previously generated Banana images to 2K or 4K ultra-high resolution.

Parameters

Field	Type	Status	Description
media_id	string	Required	mediaGenerationId UUID from banana/generate response.
project_id	string	Required	project_id from banana/generate response.
target_resolution	string	Optional	"UPSAMPLE_IMAGE_RESOLUTION_2K" or "UPSAMPLE_IMAGE_RESOLUTION_4K". Default: 2K

Example Request (curl)

curl -X POST https://gen.ssapp.vn/api/v1/image/banana/upscale \
  -H "X-API-Key: gen_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "media_id": "a37a9eca-3d78-4ad7-8acb-85e73243c675",
    "project_id": "proj_12345"
  }'

Sample Response (JSON)

{
  "success": true,
  "data": {
    "task_id": "img_ups_1786937432970",
    "type": "banana_upscale",
    "status": "pending"
  }
}

GET/account/info

Account Info & Balance

Check your current account username, available credit balance, and key metadata.

Example Request (curl)

curl https://gen.ssapp.vn/api/v1/account/info \
  -H "X-API-Key: gen_your_api_key_here"

Sample Response (JSON)

{
  "success": true,
  "data": {
    "username": "developer_pro",
    "balance": 245.5,
    "key_prefix": "gen_88f92a1b",
    "concurrent_tasks": 10
  }
}

GET/account/usage

Real-time Usage & Concurrency

Get live active task counters, 24-hour completed/failed stats, and recent task history.

Example Request (curl)

curl https://gen.ssapp.vn/api/v1/account/usage \
  -H "X-API-Key: gen_your_api_key_here"

Sample Response (JSON)

{
  "success": true,
  "data": {
    "max_concurrent_tasks": 10,
    "active_tasks": 2,
    "completed_tasks_24h": 38,
    "failed_tasks_24h": 1,
    "balance": 245.5,
    "recent_tasks": [
      {
        "task_id": "task_textto_a1b2c3d4e5f6",
        "type": "text_to_video",
        "status": "completed",
        "cost": 10,
        "created_at": "2026-03-26T14:00:00.000Z"
      }
    ]
  }
}