vinano-api-guide

name	vinano-api-guide
description	Complete guide for using the ViNano AI API — image generation, video generation, authentication, and code examples in Python/Node.js/cURL. Use when building apps with ViNano AI API or troubleshooting API errors.

ViNano AI API Guide

Your complete reference for building with the ViNano AI API. Generate images and videos using state-of-the-art AI models.

Base URL: https://vinano.ai Documentation: https://vinano.ai/api

---

Authentication

All API requests require an API key via header:

Authorization: Bearer YOUR_API_KEY

Get your API key at: https://vinano.ai/api-keys

Requirement: An active API-eligible subscription plan. See current plans at https://vinano.ai/pricing

---

Quick Start

Generate an Image (30 seconds)

curl -X POST "https://vinano.ai/api/v1/images/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "prompt=A golden retriever playing in autumn leaves, cinematic lighting"

Generate a Video (2-5 minutes)

# Step 1: Submit task
curl -X POST "https://vinano.ai/api/v1/video/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A cat playing with a ball in slow motion", "model": "veo3.1"}'

# Step 2: Poll status (use task_id from step 1)
curl "https://vinano.ai/api/v1/video/status?task_id=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Image Generation

POST /api/v1/images/generate

Supports multipart/form-data and application/json.

Parameter	Type	Required	Description
prompt	string	Yes*	Image description (max 5000 chars, returns HTTP 400 if exceeded)
model	string	No	Model ID, default gemini-2.5-flash-image-preview
image	File/File[]	No	Reference image file(s) for img2img
imageUrl	string/string[]	No	Reference image URL(s) for img2img
aspectRatio	string	No	See aspect ratio table below
img_size	string	No	1k / 2k / 4k, default 1k
mode	string	No	txt2img or img2img (auto-detected if omitted)
hdPro	string	No	Pass "true" for HD mode
googleSearch	string	No	"true" to enable search enhancement (Nano Banana 2 only)

*Either prompt or image/imageUrl must be provided

Supported Image Models

Model ID	Name	Notes
gemini-2.5-flash-image-preview	Nano Banana	Default, fastest
gemini-3.1-pro-image-preview	Nano Banana 2	Higher quality
gemini-3-pro-image-preview	Nano Banana Pro	Highest quality
sora_image	GPT-Image 2	OpenAI model
Seedance-5.0	Seedance 5.0	Supports 2k/3k output

Aspect Ratios

1:1, 16:9, 9:16, 4:3, 3:4

Output Dimensions (img_size)

img_size	1:1	16:9	9:16
1k	~1024x1024	~1280x720	~720x1280
2k	~2048x2048	~2560x1440	~1440x2560
4k	~4096x4096	~3840x2160	~2160x3840

img_size support varies by model: Nano Banana 2 / Nano Banana Pro support 1k/2k/4k; Seedance 5.0 supports 2k/3k.

Image Response (200)

{
  "status": 200,
  "images": ["https://img.vinano.ai/xxx.webp"],
  "uuid": "abc123-def456",
  "prompt": "A golden retriever...",
  "credits": { "remaining": 4500, "costCredits": 10 }
}

---

Async Image Generation (Recommended for Production)

POST /api/v1/images/async

Same parameters as /api/v1/images/generate. Returns immediately with a task_id.

{
  "status": 202,
  "task_id": "abc123-def456",
  "message": "Task submitted. Use GET /api/v1/images/task-status?task_id={task_id} to poll."
}

GET /api/v1/images/task-status?task_id=xxx

Poll until status is completed or failed.

---

Video Generation

POST /api/v1/video/generate

Parameter	Type	Required	Description
prompt	string	Yes	Video description (max 1500 chars)
model	string	Yes	veo3.1 or seedance
aspect_ratio	string	No	See model limits below
resolution	string	No	480p, 720p, 1080p
duration	number	No	Seconds (model-dependent)
image_url	string/string[]	No	Reference image(s) for img2video
video_url	string/string[]	No	Reference video(s), Seedance 2.0 Pro only (up to 3)
audio_url	string/string[]	No	Reference audio file(s), Seedance 2.0 Pro only (up to 3)
image_file	File (repeatable)	No	Upload reference files (form-data)
veo3_mode	string	No	fast or pro (veo3.1 only)
seedance_version	string	No	1.0-pro, 1.5-pro, 2.0-pro

Video Models & Limits

Model	Aspect Ratios	Resolution	Duration	Mode	Reference Input
veo3.1	16:9, 9:16, Auto	—	—	fast, pro	up to 2 reference images
seedance 1.0-pro	16:9, 9:16, 1:1, 21:9, 9:21	480p, 720p, 1080p	5, 8, 12s	—	single reference image
seedance 1.5-pro	16:9, 9:16, 1:1, 21:9, 9:21	480p, 720p, 1080p	5, 10, 12s	—	first/last frame [firstUrl, lastUrl]
seedance 2.0-pro	16:9, 9:16, 1:1, 4:3, 3:4	480p, 720p, 1080p	5, 10, 15s	—	images (≤9) + videos (≤3) + audio (≤3), total ≤12

If a parameter exceeds a model's limits, the API returns HTTP 400 with the valid values.

Video Response (202)

{
  "success": true,
  "data": {
    "task_id": "abc123-def456",
    "status": "pending",
    "credits_used": 150,
    "estimated_time": "2-5 minutes"
  }
}

GET /api/v1/video/status?task_id=xxx

Poll until status is completed:

{
  "success": true,
  "data": {
    "task_id": "abc123-def456",
    "status": "completed",
    "video_url": "https://video.vinano.ai/xxx.mp4",
    "progress": 100
  }
}

---

Code Examples

Python — Generate Image

import requests

API_KEY = "YOUR_API_KEY"
API_URL = "https://vinano.ai/api/v1/images/generate"

response = requests.post(API_URL, headers={
    "Authorization": f"Bearer {API_KEY}"
}, data={
    "prompt": "A futuristic city at sunset, cyberpunk style",
    "model": "gemini-3-pro-image-preview",
    "aspectRatio": "16:9",
    "img_size": "2k"
})

result = response.json()
if result["status"] == 200:
    print(f"Image: {result['images'][0]}")
    print(f"Credits remaining: {result['credits']['remaining']}")

Python — Generate Video with Polling

import requests, time

API_KEY = "YOUR_API_KEY"
BASE = "https://vinano.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Submit
resp = requests.post(f"{BASE}/video/generate", headers=HEADERS, json={
    "prompt": "A drone flying over a mountain landscape",
    "model": "veo3.1",
    "veo3_mode": "fast"
})
task_id = resp.json()["data"]["task_id"]
print(f"Task submitted: {task_id}")

# Poll
while True:
    status_resp = requests.get(f"{BASE}/video/status?task_id={task_id}", headers=HEADERS)
    data = status_resp.json()["data"]
    print(f"Status: {data['status']} | Progress: {data.get('progress', 0)}%")
    if data["status"] == "completed":
        print(f"Video URL: {data['video_url']}")
        break
    elif data["status"] == "failed":
        print(f"Failed: {data.get('error')}")
        break
    time.sleep(10)

Node.js — Generate Image

const response = await fetch("https://vinano.ai/api/v1/images/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A beautiful watercolor painting of a Japanese garden",
    model: "gemini-3.1-pro-image-preview",
    aspectRatio: "1:1",
    img_size: "2k"
  })
});

const result = await response.json();
console.log("Image URL:", result.images[0]);

cURL — Image-to-Image with File Upload

curl -X POST "https://vinano.ai/api/v1/images/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "prompt=Transform this photo into an oil painting style" \
  -F "image=@photo.jpg" \
  -F "model=gemini-3-pro-image-preview" \
  -F "img_size=2k"

cURL — Seedance Video with Reference Image

curl -X POST "https://vinano.ai/api/v1/video/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The woman walks gracefully along the beach at sunset",
    "model": "seedance",
    "seedance_version": "1.0-pro",
    "duration": 5,
    "resolution": "480p",
    "image_url": "https://example.com/reference.jpg"
  }'

cURL — Seedance 2.0 with Multiple Files

curl -X POST "https://vinano.ai/api/v1/video/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "prompt=Use @1 as opening scene, transition to @2 setting" \
  -F "model=seedance" \
  -F "seedance_version=2.0-pro" \
  -F "aspect_ratio=16:9" \
  -F "image_file=@scene1.jpg" \
  -F "image_file=@scene2.jpg" \
  -F "image_file=@background_music.mp3"

---

Error Handling

Code	Meaning	Action
200	Success	Parse result
202	Task submitted (video)	Poll for status
400	Bad request / Prompt too long	Check parameters
401	Invalid API key	Check Authorization header
402	Insufficient credits	Top up credits
403	No API permission	Upgrade to an API-eligible plan
429	Rate limited	Wait and retry (check Retry-After header)
500	Server error	Retry after a few seconds

---

Rate Limits

Check response headers:

• X-RateLimit-Limit — Max requests per minute
• X-RateLimit-Remaining — Remaining requests
• X-RateLimit-Reset — Seconds until reset

---

Tips

1. Use async API for production — /api/v1/images/async is more stable than sync
2. Poll with 5-10s intervals — Don't hammer the status endpoint
3. Seedance 1.5-pro for first/last frame control — Pass image_url as [firstUrl, lastUrl]
4. Seedance 2.0-pro for multi-media — Combine up to 9 images, 3 videos, and 3 audio files (≤12 total)
5. Google Search enhancement — Add "googleSearch": "true" with Nano Banana 2 for real-time context