API Documentation

Generate AI images and videos with the Genova Platform. Use the REST API, WebSocket for real-time updates, or our browser extensions for automated generation.

API v1.0Base URL: autoflow-api.aboessa101.workers.dev

7 Models

Image & Video

~30s

Image Generation

~3min

Video (Fast)

REST + WS

Real-time Updates

Quick Start

Get Your API Key

Create a Generation Job

bash

curl -X POST https://autoflow-api.aboessa101.workers.dev/api/jobs \
  -H "X-API-Key: af_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "prompt": "A cat playing piano in a jazz club",
    "model": "imagen4",
    "aspectRatio": "landscape",
    "count": 1
  }'

json

{
  "success": true,
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "queuePosition": 1,
  "estimatedTime": 30
}

Check Status & Download

bash

# Poll status
curl https://autoflow-api.aboessa101.workers.dev/api/jobs/JOB_ID \
  -H "X-API-Key: af_your_api_key_here"

# Download when completed
curl https://autoflow-api.aboessa101.workers.dev/api/jobs/JOB_ID/download \
  -H "X-API-Key: af_your_api_key_here"

Authentication

All API requests require authentication. Two methods are supported:

Recommended

API Key

Send in the X-API-Key header.

Alternative

JWT Bearer Token

Send in the Authorization: Bearer <token> header.

bash

# API Key (recommended for server-to-server)
curl -H "X-API-Key: af_your_api_key_here" ...

# JWT Token (used by web dashboard and extensions)
curl -H "Authorization: Bearer eyJhbGciOi..." ...

Available Models

Genova supports 7 AI models across two platforms: Google Flow (images & videos) and Freepik Pikaso (images).

Image Models

imagen4Imagen 4

Google Flow

Google’s latest image generation model. Best overall quality and prompt adherence. Supports reference images.

~30s ExcellentAspect: landscape, portrait, squareCount: 1-4

nano_banana_proNano Banana Pro

Google Flow

Fast community model optimized for artistic styles. Good for creative/stylized outputs.

~20s GoodAspect: landscape, portrait, squareCount: 1-4

nano_banana2Nano Banana 2

Google Flow

Updated community model with improved realism. Good for photo-realistic generations.

~20s GoodAspect: landscape, portrait, squareCount: 1-4

Video Models

veo3_fastVEO 3 Fast

Google Flow

Google’s VEO 3 in fast mode. Generates high-quality videos with good prompt adherence in under 3 minutes.

~2-3 min ExcellentAspect: landscape, portrait, squareCount: 1

veo3_qualityVEO 3 Quality

Google Flow

VEO 3 at maximum quality. Slower but produces cinema-grade video output with superior detail.

~5-8 min PremiumAspect: landscape, portrait, squareCount: 1

veo2_fastVEO 2 Fast

Google Flow

Previous generation VEO model. Fastest video generation, ideal for drafts and rapid iteration.

~1-2 min GoodAspect: landscape, portrait, squareCount: 1

Freepik Model

freepikFreepik Pikaso AI

Freepik

Freepik's Pikaso AI image generator. Supports 7 aspect ratios, 2 resolutions, up to 4 images per generation, and 6 reference image modes for style-guided generation.

~20-40s Good7 aspect ratios1K / 2K resolutionCount: 1-4

Freepik-specific settings:

resolution — "1K" or "2K"

referenceImages.mode — see Reference Images

Dimensions & Aspect Ratios

Google Flow Models

(imagen4, nano_banana_pro, nano_banana2, veo3_*, veo2_*)

Value	Ratio	Best For
`landscape`	16:9	Desktop wallpapers, YouTube thumbnails, presentations
`portrait`	9:16	Mobile wallpapers, Instagram stories, TikTok
`square`	1:1	Social media posts, profile pictures, thumbnails

Pass as aspectRatio in the job settings.

Freepik Model

(model: "freepik")

Value	Description	Best For
`1:1`	Square	Social media, icons
`4:3`	Standard	Presentations, blog images
`3:4`	Portrait	Posters, book covers
`16:9`	Widescreen	Desktop backgrounds, banners
`9:16`	Tall / Stories	Phone wallpapers, stories
`3:2`	Photo landscape	Photography-style images
`2:3`	Photo portrait	Portrait photography

Resolution Options

1KStandard resolution (default)

2KHigh quality, larger file size

Reference Images

Upload reference images to guide the AI generation. Images should be sent as base64-encoded strings. The API normalizes them automatically.

Request Format

json

{
  "type": "image",
  "prompt": "A sunset over mountains",
  "model": "imagen4",
  "referenceImages": {
    "images": [
      "data:image/jpeg;base64,/9j/4AAQSkZ...",
      "data:image/png;base64,iVBORw0KGgo..."
    ],
    "mode": "ingredients"
  }
}

Images can be sent as full data URLs (data:image/...;base64,...) or plain base64 strings. Maximum 4 reference images per request. Images are auto-resized to 512px max dimension.

Reference Modes

Mode	Platform	Description
`ingredients`	Flow	Combines elements from your reference images into the generated image
`style`	Freepik	Applies the artistic style of the reference to the generation
`character`	Freepik	Uses a character/person from the reference in the output
`element`	Freepik	Incorporates specific visual elements from the reference
`color`	Freepik	Matches the color palette of the reference image
`effects`	Freepik	Applies visual effects (lighting, texture) from the reference
`camera`	Freepik	Matches the camera angle and perspective of the reference

API Reference

Base URL: https://autoflow-api.aboessa101.workers.dev

POST/api/jobsCreate Generation Job

Creates a new image or video generation job. Deducts 1 credit.

Parameter	Type	Req	Description
`type`	string	Yes	"image" or "video"
`prompt`	string	Yes	Text description (max 500 chars)
`model`	string	No	See Available Models. Default: "imagen4"
`aspectRatio`	string	No	Flow: "landscape" / "portrait" / "square". Freepik: "1:1" / "4:3" / "3:4" / "16:9" / "9:16" / "3:2" / "2:3". Default: "landscape"
`count`	number	No	Number of items (1-4). Videos always 1. Default: 1
`quality`	string	No	Freepik only: "1K" or "2K". Default: "1K"
`referenceImages`	object	No	{ images: string[], mode: string }. See Reference Images section
`priority`	number	No	Queue priority (higher = sooner). Default: 0

Examples:

json

// Image with Imagen 4
{
  "type": "image",
  "prompt": "A futuristic cityscape at sunset",
  "model": "imagen4",
  "aspectRatio": "landscape",
  "count": 2
}

// Video with VEO 3
{
  "type": "video",
  "prompt": "A drone flyover of a coral reef",
  "model": "veo3_fast",
  "aspectRatio": "landscape"
}

// Freepik with reference image
{
  "type": "image",
  "prompt": "A portrait in this style",
  "model": "freepik",
  "aspectRatio": "1:1",
  "count": 4,
  "quality": "2K",
  "referenceImages": {
    "images": ["data:image/jpeg;base64,..."],
    "mode": "style"
  }
}

GET/api/jobs/:idGet Job Status

Retrieve the full details and current status of a generation job.

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "image",
  "status": "completed",
  "prompt": "A cat playing piano in a jazz club",
  "settings": {
    "model": "imagen4",
    "aspectRatio": "landscape",
    "count": 1
  },
  "result_url": "generated/user-id/job-id/result.png",
  "result_urls": null,
  "created_at": "2025-04-02T10:30:00Z",
  "started_at": "2025-04-02T10:30:02Z",
  "completed_at": "2025-04-02T10:30:32Z",
  "processing_time": 30,
  "file_size": 1048576
}

GET/api/jobsList Jobs

List your generation jobs with optional filtering and pagination.

Query Param	Type	Description
`status`	string	Filter: "pending", "queued", "processing", "completed", "failed"
`limit`	number	Max results per page (default: 50)
`offset`	number	Pagination offset (default: 0)

json

{
  "jobs": [
    { "id": "...", "type": "image", "status": "completed", "prompt": "...", ... },
    { "id": "...", "type": "video", "status": "processing", "prompt": "...", ... }
  ],
  "total": 42
}

GET/api/jobs/:id/downloadDownload Result

Get a signed download URL for a completed job. Redirects to the file. Only works for jobs with status completed.

bash

curl -L https://autoflow-api.aboessa101.workers.dev/api/jobs/JOB_ID/download \
  -H "X-API-Key: af_your_api_key_here" \
  -o result.png

DELETE/api/jobs/:idCancel Job

Cancel a pending or queued job. Credits are refunded if the job hasn't started processing. Returns { "success": true }.

API Key Management

POST

/api/keys

Create a new API key. Body: { "name": "My Key" }. Returns the full key (shown only once).

GET

/api/keys

List all active (non-revoked) API keys with prefix and metadata.

DELETE

/api/keys/:id

Permanently revoke an API key. Cannot be undone.

User & Statistics

GET

/api/user/me

Get your profile: id, email, name, subscription plan/status, credits remaining/used.

PATCH

/api/user/me

Update profile: { "name": "New Name" }

GET

/api/user/stats

Generation statistics: total/completed/failed/active jobs, image/video counts, credits remaining.

WebSocket (Real-time Updates)

Connect via WebSocket to receive real-time job status updates instead of polling. The dashboard and extensions both use this for instant notifications.

User Connection (Dashboard)

javascript

const ws = new WebSocket(
  'wss://autoflow-api.aboessa101.workers.dev/ws/user?userId=YOUR_USER_ID'
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg);
  // msg.type can be:
  //   "welcome"       — connection confirmed
  //   "job_started"   — extension picked up your job
  //   "job_progress"  — progress update with percentage
  //   "job_completed" — job done, includes resultUrl
  //   "job_failed"    — job failed, includes error message
};

Message Types

Type	Direction	Fields
`welcome`	Server → Client	{ type, userId }
`job_started`	Server → Client	{ type, jobId }
`job_progress`	Server → Client	{ type, jobId, progress, message }
`job_completed`	Server → Client	{ type, jobId, resultUrl, resultUrls }
`job_failed`	Server → Client	{ type, jobId, error }
`ping`	Client → Server	{ type: "ping" } — keep-alive
`pong`	Server → Client	{ type: "pong" } — heartbeat reply

Extension Connection

Browser extensions connect to a separate endpoint and receive job assignments:

javascript

// Extension WebSocket (used internally by Flow/Freepik extensions)
const ws = new WebSocket(
  'wss://autoflow-api.aboessa101.workers.dev/ws/extension' +
  '?userId=USER_ID&token=JWT_TOKEN&extensionType=flow'
  // extensionType: "flow" or "freepik"
);

// Extension receives:  new_job (assigned work)
// Extension sends:     job_progress, job_completed, job_failed, request_job

Job Lifecycle

pending

queued

processing

completed

pendingJob created, waiting for an available extension to pick it up.

queuedJob is in the queue and will be assigned to the next idle extension of the matching type (Flow or Freepik).

processingAn extension is actively generating content. Progress updates are sent via WebSocket. Stuck jobs are auto-failed after 15 minutes.

completedGeneration finished. Result is uploaded to R2 storage. Use the download endpoint to retrieve it.

failedGeneration failed. Check error_message for details. Jobs queued for 30+ minutes without assignment are auto-failed.

Rate Limits

Plan	Requests/min	Concurrent Jobs	Monthly Credits
Free	10	2	50
Starter	60	5	500
Pro	100	10	2,000
Business	300	25	10,000

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.

Error Codes

Code	Description	Resolution
`200`	OK	Request succeeded
`201`	Created	Resource created successfully (job, API key)
`400`	Bad Request	Check required parameters: type, prompt are required
`401`	Unauthorized	Verify your API key or JWT token is valid and not expired
`402`	Payment Required	Insufficient credits. Upgrade your plan or purchase more credits
`403`	Forbidden	You don't have permission for this resource
`404`	Not Found	Job or resource doesn't exist. Check the ID
`429`	Rate Limited	Wait and retry. Check Retry-After header
`500`	Server Error	Internal error — retry the request

Error Response Format

json

{
  "error": "Missing required fields",
  "details": "prompt is required"
}

Browser Extensions

Genova uses Chrome extensions as generation workers. Each extension connects to the platform via WebSocket, receives job assignments, and uploads results automatically.

Flow Image Automator

Handles all Google Flow models (Imagen 4, Nano Banana, VEO 2/3). Captures generated media from the Flow interface and uploads to R2.

Models: imagen4, nano_banana_pro, nano_banana2, veo3_fast, veo3_quality, veo2_fast

Platform: flow.google.com

Genova Images (Freepik)

Handles Freepik Pikaso AI model. Supports 6 reference image modes, 7 aspect ratios, and 2 resolution options.

Model: freepik

Platform: freepik.com/pikaso

How it works: When you create a job via the API or dashboard, the Job Manager routes it to the correct extension type based on the model. Jobs with model: "freepik" go to the Freepik extension; all others go to Flow. The extension generates the content in the background, uploads the result to cloud storage, and reports completion.