REST API · v1
AI video generation API
Text-to-video and image-to-video with sound over plain HTTPS. Same price as the website: $1 per video, free signup videos count too. No subscription, no minimum volume. Every format from TikTok to Pinterest.
Quick start
Authenticate with Authorization: Bearer gv_…. Create a video, then poll until status is done.
curl -X POST https://generatorvideo.ai/api/v1/videos \
-H "Authorization: Bearer $GV_KEY" -H "Content-Type: application/json" \
-d '{"prompt":"a golden retriever surfing a giant wave at sunset","format":"tiktok","duration":5,"model":"fast"}'
# → 201 {"ok":true,"video":{"id":"aB3dE5fG7h","status":"queued","eta_seconds":30,...}}
curl https://generatorvideo.ai/api/v1/videos/aB3dE5fG7h -H "Authorization: Bearer $GV_KEY"
# → {"ok":true,"video":{"status":"done","video_url":"https://generatorvideo.ai/media/v/…/aB3dE5fG7h.mp4",...}}
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /api/v1/formats | Formats, models, styles, limits, price (no key needed) |
| GET | /api/v1/me | Balance, free videos, videos left |
| POST | /api/v1/videos | Create a video (charges $1 or one free video) |
| GET | /api/v1/videos | List your videos (limit, cursor) |
| GET | /api/v1/videos/{id} | Status, URLs, queue position, ETA |
| POST | /api/v1/videos/{id} | Update: {"public": false} |
| POST | /api/v1/videos/{id}/export | Re-render for another network: {"format":"youtube","mode":"fit|fill"} |
| DELETE | /api/v1/videos/{id} | Delete (queued videos are refunded) |
Create parameters
| Field | Type | Notes |
|---|---|---|
prompt | string | Required, 3–1500 chars. Any language. |
format | string | tiktok, reels, shorts, youtube, x, square, portrait, pinterest, linkedin (default tiktok) |
model | string | fast (Turbo, default) |
duration | int | 3–30 seconds (default 5). Free videos: 3, 5 or 8 s; longer clips are charged $1 from balance |
audio | bool | Generate synchronized sound (default true) |
style | string | cinematic, photoreal, anime, 3d, clay, documentary, vhs, cyberpunk, watercolor, noir, drone, product |
image_urls / images_b64 | string[] | Optional 1–10 photos (JPG/PNG/WEBP ≤ 10 MB each). One photo = first frame; several = keyframes spread across the clip. image_url / image_b64 still accepted for a single photo |
photo_mode | string | start — photo 1 is the first frame (default for 1 photo); keyframes — every photo is a fixed frame on the timeline; reference — photos set the look of the person/object, the scene comes from the prompt |
negative, seed | string, int | Optional |
public | bool | Publish to the public feed (default false — videos are private until published) |
Errors
401 invalid key · 402 insufficient_balance — top up · 422 validation or content policy · 429 rate limit (120 req/min). Failed renders are refunded automatically.
Python
import requests, time
H = {"Authorization": "Bearer gv_..."}
v = requests.post("https://generatorvideo.ai/api/v1/videos", headers=H, json={"prompt": "a cat dj in a neon club", "format": "reels"}).json()["video"]
while v["status"] in ("queued", "running"):
time.sleep(3)
v = requests.get(f"https://generatorvideo.ai/api/v1/videos/{v['id']}", headers=H).json()["video"]
print(v["video_url"])
