# VicSee — Full API & Product Reference

> VicSee is an AI video and image generation platform. Create cinematic videos and stunning images using state-of-the-art models through a unified web interface or REST API. Credit-based pricing — mix and match models freely.

Website: https://vicsee.com
API Base URL: https://vicsee.com/api/v1
Support: support@vicsee.com

---

## Authentication

All API requests (except GET /api/v1/models) require a Bearer token.

API keys start with `sk-` and are created at https://vicsee.com/settings/apikeys

Header: `Authorization: Bearer sk-your-api-key`

API access requires paid status (active subscription or credit pack purchase). Free accounts cannot use the API.

### Error Responses (401)

| Code | Message |
|------|---------|
| MISSING_AUTH_HEADER | No Authorization header provided |
| INVALID_AUTH_FORMAT | Invalid Authorization format (use "Bearer sk-xxx") |
| INVALID_KEY_FORMAT | Key doesn't start with sk- |
| INVALID_API_KEY | Key not found or inactive |

---

## API Workflow

VicSee uses async generation:

1. POST /api/v1/generate — Submit a generation task
2. POST /api/v1/tools/upscale — Upscale an image (dedicated endpoint, 3 credits)
3. GET /api/v1/tasks/{id} — Poll until status is "completed"
4. Download the result from the URL in the response

### Generate Endpoint

```
POST https://vicsee.com/api/v1/generate
Content-Type: application/json
Authorization: Bearer sk-your-api-key
```

Request body:
```json
{
  "model": "model-id",
  "input": {
    "prompt": "Your description",
    ...model-specific parameters
  }
}
```

Response:
```json
{
  "success": true,
  "data": {
    "id": "task_abc123",
    "model": "model-id",
    "status": "pending",
    "creditsUsed": 20,
    "creditsRemaining": 480,
    "createdAt": "2026-02-11T12:00:00Z"
  }
}
```

### Task Polling Endpoint

```
GET https://vicsee.com/api/v1/tasks/{id}
Authorization: Bearer sk-your-api-key
```

Response (processing):
```json
{
  "success": true,
  "data": {
    "id": "task_abc123",
    "model": "model-id",
    "status": "processing",
    "mediaType": "video",
    "prompt": "Your description",
    "result": null
  }
}
```

Response (complete):
```json
{
  "success": true,
  "data": {
    "id": "task_abc123",
    "model": "model-id",
    "status": "completed",
    "mediaType": "video",
    "prompt": "Your description",
    "result": {
      "url": "https://cdn.vicsee.com/outputs/video_xyz.mp4",
      "type": "video"
    }
  }
}
```

Status values: pending, processing, completed, failed

### Credits Endpoint

```
GET https://vicsee.com/api/v1/credits
Authorization: Bearer sk-your-api-key
```

Response:
```json
{
  "success": true,
  "data": {
    "credits": 4250
  }
}
```

### Models Endpoint (Public)

```
GET https://vicsee.com/api/v1/models
```

No authentication required. Returns list of available models.

---

## Rate Limits

| Plan | Requests/Day |
|------|-------------|
| Free | 0 (no API access) |
| Starter | 100 |
| Pro | 500 |

Headers in every response:
- X-RateLimit-Limit: Max requests per day
- X-RateLimit-Remaining: Requests left today
- X-RateLimit-Reset: When limit resets (ISO 8601)

---

## Error Codes

| Status | Code | Message |
|--------|------|---------|
| 400 | INVALID_JSON | Invalid JSON body |
| 400 | MISSING_MODEL | model is required |
| 400 | MISSING_PROMPT | prompt is required |
| 400 | INVALID_MODEL | Model does not exist |
| 401 | MISSING_AUTH_HEADER | No Authorization header |
| 401 | INVALID_KEY_FORMAT | Key doesn't start with sk- |
| 401 | INVALID_API_KEY | Key not found or inactive |
| 402 | INSUFFICIENT_CREDITS | Not enough credits |
| 403 | FORBIDDEN | API access requires an active subscription or credit pack |
| 403 | FORBIDDEN | Access denied (task belongs to another user) |
| 404 | TASK_NOT_FOUND | Task ID doesn't exist |
| 429 | RATE_LIMITED | Rate limit exceeded |
| 500 | PROVIDER_ERROR | AI provider not available |
| 500 | GENERATION_FAILED | Generation failed |
| 500 | INTERNAL_ERROR | Internal server error |

---

## Video Models

### VicSee 1.0 (Default)

Model IDs: `vicsee-standard-text-to-video`, `vicsee-standard-image-to-video`
Capabilities: Text to Video, Image to Video
Duration: 8 seconds (fixed)
Resolution: 720p
Audio: Native (automatic)
Credits: 28
Engine: Veo 3.1 Fast (house blend — same quality, simplified controls)

This is the default model new users see. It uses Veo 3.1 Fast under the hood with locked settings for a simple, one-click experience.

Parameters (text-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "vicsee-standard-text-to-video" |
| input.prompt | string | Yes | Max 2,000 chars |
| input.aspect_ratio | string | No | "16:9", "9:16" (default: "16:9") |

Parameters (image-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "vicsee-standard-image-to-video" |
| input.prompt | string | Yes | Max 2,000 chars |
| input.image_urls | string[] | Yes | 1 image URL |
| input.aspect_ratio | string | No | "16:9", "9:16" (default: "16:9") |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vicsee-standard-text-to-video",
    "input": {
      "prompt": "A cozy coffee shop, barista steaming milk, jazz music playing softly",
      "aspect_ratio": "16:9"
    }
  }'
```

---

### Sora 2

Model IDs: `sora-2-text-to-video`, `sora-2-image-to-video`
Capabilities: Text to Video, Image to Video
Duration: 10 or 15 seconds
Resolution: 720p
Audio: Native (automatic)
Credits: 10s = 20, 15s = 30

Parameters (text-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "sora-2-text-to-video" |
| input.prompt | string | Yes | Max 10,000 chars |
| input.duration | number | No | 10 or 15 (default: 10) |
| input.aspect_ratio | string | No | "landscape" (16:9), "portrait" (9:16). Default: "landscape" |

Parameters (image-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "sora-2-image-to-video" |
| input.prompt | string | Yes | Max 10,000 chars |
| input.image_urls | string[] | Yes | Exactly 1 image URL |
| input.duration | number | No | 10 or 15 (default: 10) |
| input.aspect_ratio | string | No | "landscape", "portrait" (default: "landscape") |

Note: OpenAI policy may reject images containing real human faces. Use illustrations or landscapes.

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2-text-to-video",
    "input": {
      "prompt": "A cat walking across a piano, playing random notes, sunlight streaming through window",
      "duration": 10,
      "aspect_ratio": "landscape"
    }
  }'
```

---

### Sora 2 Pro

Model IDs: `sora-2-pro-text-to-video`, `sora-2-pro-image-to-video`
Capabilities: Text to Video, Image to Video
Duration: 10 or 15 seconds
Resolution: 720p (standard) or 1080p (hd)
Audio: Native (automatic)
Credits: 10s standard = 105, 15s standard = 190, 10s HD = 230, 15s HD = 440

Parameters (text-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "sora-2-pro-text-to-video" |
| input.prompt | string | Yes | Text description |
| input.duration | number | No | 10 or 15 (default: 10) |
| input.aspect_ratio | string | No | "landscape" (16:9) or "portrait" (9:16). Default: "landscape" |
| input.quality | string | No | "standard" (720p) or "hd" (1080p, default) |

Parameters (image-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "sora-2-pro-image-to-video" |
| input.prompt | string | Yes | Text description |
| input.image_urls | string[] | Yes | Exactly 1 image URL |
| input.duration | number | No | 10 or 15 (default: 10) |
| input.aspect_ratio | string | No | "landscape" (16:9) or "portrait" (9:16). Default: "landscape" |
| input.quality | string | No | "standard" or "hd" (default) |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2-pro-text-to-video",
    "input": {
      "prompt": "A cinematic shot of a mountain landscape at sunset",
      "duration": 10,
      "quality": "hd",
      "aspect_ratio": "landscape"
    }
  }'
```

---

### Veo 3.1

Model IDs: `veo-3-1-text-to-video`, `veo-3-1-quality-text-to-video`, `veo-3-1-image-to-video`, `veo-3-1-quality-image-to-video`
Capabilities: Text to Video, Image to Video (single frame or first+last frame)
Duration: ~8 seconds
Resolution: 720p (Fast) to 4K (Quality)
Audio: Native (automatic, based on prompt)
Credits: Fast = 58, Fast 4K = 175, Quality = 300, Quality 4K = 960

Parameters (text-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "veo-3-1-text-to-video" (fast, 58cr) or "veo-3-1-quality-text-to-video" (300cr) |
| input.prompt | string | Yes | Include audio cues for best results |
| input.aspect_ratio | string | No | "16:9", "9:16", "Auto" (default: "16:9") |

Parameters (image-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "veo-3-1-image-to-video" (fast) or "veo-3-1-quality-image-to-video" |
| input.prompt | string | Yes | Description of animation |
| input.image_urls | string[] | Yes | 1 image (animate) or 2 images (transition from first to last) |
| input.aspect_ratio | string | No | "16:9", "9:16", "Auto" (default: "16:9") |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3-1-text-to-video",
    "input": {
      "prompt": "Drone shot flying over a tropical beach, waves crashing, seagulls calling",
      "aspect_ratio": "16:9"
    }
  }'
```

---

### Kling 3.0

Model IDs: `kling-3-0-text-to-video`, `kling-3-0-image-to-video`
Capabilities: Text to Video, Image to Video (start frame + optional end frame)
Duration: 3-15 seconds (any integer)
Quality: Standard or Professional
Audio: Optional (on by default)
Credits: Per-second pricing. Standard no-audio = 28/s, Standard+audio = 42/s, Professional no-audio = 38/s, Professional+audio = 56/s. Range: 84-840.

Parameters (text-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "kling-3-0-text-to-video" |
| input.prompt | string | Yes | Max 2500 chars |
| input.duration | number | No | 3-15 (default: 5) |
| input.mode | string | No | "standard" or "professional" (default: "standard") |
| input.sound | boolean | No | true/false (default: true) |
| input.aspect_ratio | string | No | "16:9", "9:16", "1:1" (default: "16:9") |

Parameters (image-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "kling-3-0-image-to-video" |
| input.prompt | string | Yes | Description of animation |
| input.image_urls | string[] | Yes | 1-2 images (start frame, optional end frame) |
| input.duration | number | No | 3-15 (default: 5) |
| input.mode | string | No | "standard" or "professional" (default: "standard") |
| input.sound | boolean | No | true/false (default: true) |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3-0-text-to-video",
    "input": {
      "prompt": "A cinematic tracking shot through a neon-lit Tokyo street at night",
      "duration": 10,
      "mode": "professional",
      "sound": true,
      "aspect_ratio": "16:9"
    }
  }'
```

---

### Kling 2.6

Model IDs: `kling-2-6-text-to-video`, `kling-2-6-image-to-video`
Capabilities: Text to Video, Image to Video
Duration: 5 or 10 seconds
Resolution: 1080p
Audio: Optional (dialogue, lip-sync)
Credits: 5s no-audio = 75, 10s no-audio = 150, 5s+audio = 150, 10s+audio = 300

Parameters (text-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "kling-2-6-text-to-video" |
| input.prompt | string | Yes | Text description |
| input.duration | number | No | 5 or 10 (default: 5) |
| input.aspect_ratio | string | No | "16:9", "9:16", "1:1" (default: "16:9") |
| input.sound | boolean | No | true/false (default: false) |

Parameters (image-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "kling-2-6-image-to-video" |
| input.prompt | string | Yes | Description of animation/dialogue |
| input.image_urls | string[] | Yes | 1 image URL |
| input.duration | number | No | 5 or 10 (default: 5) |
| input.aspect_ratio | string | No | "16:9", "9:16", "1:1" |
| input.sound | boolean | No | true/false (default: false) |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2-6-text-to-video",
    "input": {
      "prompt": "A person saying Welcome to our channel with a friendly smile",
      "duration": 5,
      "sound": true,
      "aspect_ratio": "16:9"
    }
  }'
```

---

### Seedance 1.5 Pro

Model IDs: `seedance-1-5-pro-text-to-video`, `seedance-1-5-pro-image-to-video`
Capabilities: Text to Video, Image to Video
Duration: 4, 8, or 12 seconds (12s not available at 480p)
Resolution: 480p, 720p, 1080p
Audio: Optional multilingual (8+ languages)
Credits: 15-260 (depends on resolution, duration, audio)

Parameters (text-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "seedance-1-5-pro-text-to-video" |
| input.prompt | string | Yes | Max 2500 chars |
| input.duration | number | No | 4, 8, or 12 (default: 4) |
| input.resolution | string | No | "480p", "720p", "1080p" (default: "480p") |
| input.aspect_ratio | string | No | "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" (default: "16:9") |
| input.sound | boolean | No | true/false (default: false) |

Parameters (image-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "seedance-1-5-pro-image-to-video" |
| input.prompt | string | Yes | Description of animation |
| input.image_urls | string[] | Yes | 1-2 reference images |
| input.duration | number | No | 4, 8, or 12 (default: 4) |
| input.resolution | string | No | "480p", "720p", "1080p" (default: "480p") |
| input.sound | boolean | No | true/false (default: false) |

Pricing table:
| Resolution | Duration | Audio | Credits |
|------------|----------|-------|---------|
| 480p | 4s | No | 15 |
| 480p | 4s | Yes | 28 |
| 480p | 8s | No | 28 |
| 480p | 8s | Yes | 48 |
| 720p | 4s | No | 28 |
| 720p | 4s | Yes | 48 |
| 720p | 8s | No | 48 |
| 720p | 8s | Yes | 80 |
| 720p | 12s | No | 60 |
| 720p | 12s | Yes | 120 |
| 1080p | 4s | No | 50 |
| 1080p | 4s | Yes | 85 |
| 1080p | 8s | No | 85 |
| 1080p | 8s | Yes | 170 |
| 1080p | 12s | No | 130 |
| 1080p | 12s | Yes | 260 |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1-5-pro-text-to-video",
    "input": {
      "prompt": "A bartender greets customers: Welcome, what can I get for you?",
      "duration": 4,
      "resolution": "720p",
      "sound": true,
      "aspect_ratio": "16:9"
    }
  }'
```

---

### Seedance 1.0

Model IDs: `seedance-1-0-text-to-video`, `seedance-1-0-image-to-video`
Capabilities: Text to Video, Image to Video
Duration: 5 or 10 seconds
Resolution: 480p, 720p
Audio: Not supported
Credits: 480p/5s = 28, 480p/10s = 48, 720p/5s = 50, 720p/10s = 100

Parameters (text-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "seedance-1-0-text-to-video" |
| input.prompt | string | Yes | Max 10,000 chars |
| input.duration | number | No | 5 or 10 (default: 5) |
| input.resolution | string | No | "480p", "720p" (default: "480p") |
| input.aspect_ratio | string | No | "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" (default: "16:9") |

Parameters (image-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "seedance-1-0-image-to-video" |
| input.prompt | string | Yes | Description of animation |
| input.image_urls | string[] | Yes | 1 reference image |
| input.duration | number | No | 5 or 10 (default: 5) |
| input.resolution | string | No | "480p", "720p" (default: "480p") |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1-0-text-to-video",
    "input": {
      "prompt": "A boy rides a bike down a golden-lit rural road at sunset",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'
```

---

### Wan 2.6

Model IDs: `wan-2-6-text-to-video`, `wan-2-6-image-to-video`
Capabilities: Text to Video, Image to Video
Duration: 5, 10, or 15 seconds
Resolution: 720p, 1080p
Audio: Not specified
Multi-shot: Automatic camera angle changes and cuts (enabled by default)
Credits: 5s/720p = 100, 10s/720p = 200, 15s/720p = 300, 5s/1080p = 150, 10s/1080p = 300, 15s/1080p = 450

Parameters (text-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "wan-2-6-text-to-video" |
| input.prompt | string | Yes | Max 5000 chars |
| input.duration | number | No | 5, 10, or 15 (default: 5) |
| input.resolution | string | No | "720p", "1080p" (default: "720p") |
| input.multi_shots | boolean | No | true/false (default: true) |

Parameters (image-to-video):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "wan-2-6-image-to-video" |
| input.prompt | string | Yes | Description of animation |
| input.image_urls | string[] | Yes | 1 starting image |
| input.duration | number | No | 5, 10, or 15 (default: 5) |
| input.resolution | string | No | "720p", "1080p" (default: "720p") |
| input.multi_shots | boolean | No | true/false (default: true) |

Note: No aspect ratio parameter. Videos use the model's default ratio.

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-2-6-text-to-video",
    "input": {
      "prompt": "A cinematic drone shot over mountain peaks at sunrise, revealing a misty valley",
      "duration": 10,
      "resolution": "1080p",
      "multi_shots": true
    }
  }'
```

---

### Hailuo 2.3

Model IDs: `hailuo-2-3-standard`, `hailuo-2-3-pro`
Capabilities: Image to Video only (no text-to-video)
Duration: 6 or 10 seconds (as string)
Resolution: 768P, 1080P (10s at 1080P not supported)
Audio: Not supported
Credits: Standard 6s/768P = 35, Standard 10s/768P = 55, Standard 6s/1080P = 55, Pro 6s/768P = 55, Pro 10s/768P = 110, Pro 6s/1080P = 100

Parameters:
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "hailuo-2-3-standard" or "hailuo-2-3-pro" |
| input.prompt | string | Yes | Max 5000 chars |
| input.image_urls | string[] | Yes | 1 image URL |
| input.duration | string | No | "6" or "10" (default: "6") — NOTE: string type, not number |
| input.resolution | string | No | "768P" or "1080P" (default: "768P") |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2-3-pro",
    "input": {
      "prompt": "The character turns to face the camera with a gentle smile",
      "image_urls": ["https://example.com/portrait.jpg"],
      "duration": "6",
      "resolution": "1080P"
    }
  }'
```

---

## Image Models

### VicSee Image 1.0 (Default)

Model IDs: `vicsee-standard-text-to-image`, `vicsee-standard-image-to-image`
Engine: Nano Banana (house blend — same quality, simplified controls)
Credits: 6

This is the default image model. It uses Nano Banana under the hood with simplified settings.

Parameters (text-to-image):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "vicsee-standard-text-to-image" |
| input.prompt | string | Yes | Max 2,000 chars |
| input.aspect_ratio | string | No | "1:1", "16:9", "9:16", "4:3", "3:4" (default: "1:1") |

Parameters (image-to-image):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "vicsee-standard-image-to-image" |
| input.prompt | string | Yes | Description of changes |
| input.image_urls | string[] | Yes | 1 image URL |
| input.aspect_ratio | string | No | "1:1", "16:9", "9:16", "4:3", "3:4" (default: "1:1") |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vicsee-standard-text-to-image",
    "input": {
      "prompt": "A golden retriever puppy playing in autumn leaves, photorealistic",
      "aspect_ratio": "1:1"
    }
  }'
```

---

### Nano Banana

Model IDs: `nano-banana-text-to-image`, `nano-banana-image-to-image`, `nano-banana-upscale`
Engine: Google Imagen
Credits: Generate = 9, Edit = 9, Upscale = 3

Parameters (text-to-image):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "nano-banana-text-to-image" |
| input.prompt | string | Yes | Text description |
| input.aspect_ratio | string | No | "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5", "21:9" |
| input.output_format | string | No | "png" or "jpeg" (default: "png") |

Parameters (image-to-image):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "nano-banana-image-to-image" |
| input.prompt | string | Yes | Description of changes |
| input.image_urls | string[] | Yes | 1 image URL |
| input.output_format | string | No | "png" or "jpeg" (default: "png") |

Parameters (upscale):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "nano-banana-upscale" |
| input.image_urls | string[] | Yes | 1 image URL |
| input.scale | number | No | 2 or 4 (default: 2) |
| input.face_enhance | boolean | No | true/false (default: false) |

Example (text-to-image):
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-text-to-image",
    "input": {
      "prompt": "A serene mountain landscape at sunset, photorealistic",
      "aspect_ratio": "16:9"
    }
  }'
```

Example (upscale):
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-upscale",
    "input": {
      "image_urls": ["https://example.com/photo.jpg"],
      "scale": 4,
      "face_enhance": true
    }
  }'
```

Dedicated upscale endpoint (simpler interface, same result):
```bash
curl -X POST https://vicsee.com/api/v1/tools/upscale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "scale": 4,
    "face_enhance": true
  }'
```

---

### Nano Banana Pro

Model IDs: `nano-banana-pro-text-to-image`, `nano-banana-pro-image-to-image`
Engine: Google Imagen Pro
Resolution: 1K (1024px), 2K (2048px), 4K (4096px)
Credits: 1K = 18, 2K = 18, 4K = 36

Parameters (text-to-image):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "nano-banana-pro-text-to-image" |
| input.prompt | string | Yes | Text description |
| input.resolution | string | No | "1K", "2K", "4K" (default: "1K") |
| input.aspect_ratio | string | No | "1:1", "16:9", "9:16", "4:3", "3:4", "2:3", "3:2", "4:5", "5:4", "21:9" |
| input.output_format | string | No | "png" or "jpg" (default: "png") |

Parameters (image-to-image):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "nano-banana-pro-image-to-image" |
| input.prompt | string | Yes | Description of transformation |
| input.image_urls | string[] | Yes | 1-8 image URLs |
| input.resolution | string | No | "1K", "2K", "4K" (default: "1K") |
| input.aspect_ratio | string | No | Output aspect ratio |
| input.output_format | string | No | "png" or "jpg" (default: "png") |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro-text-to-image",
    "input": {
      "prompt": "Hyperrealistic portrait, dramatic lighting, museum-quality",
      "resolution": "4K",
      "aspect_ratio": "3:4"
    }
  }'
```

---

### FLUX 2

Model IDs: `flux-2-pro-text-to-image`, `flux-2-pro-image-to-image`, `flux-2-flex-text-to-image`, `flux-2-flex-image-to-image`
Engine: Black Forest Labs FLUX.2
Variants: Pro (fast, production) and Flex (max quality)
Resolution: 1K, 2K
Credits: Pro 1K = 15, Pro 2K = 20, Flex 1K = 45, Flex 2K = 75

Parameters (text-to-image):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "flux-2-pro-text-to-image" or "flux-2-flex-text-to-image" |
| input.prompt | string | Yes | 3-5000 characters |
| input.resolution | string | No | "1K" or "2K" (default: "1K") |
| input.aspect_ratio | string | No | "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "auto" |

Parameters (image-to-image / multi-reference):
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "flux-2-pro-image-to-image" or "flux-2-flex-image-to-image" |
| input.prompt | string | Yes | Description of output |
| input.image_urls | string[] | Yes | 1-8 reference images |
| input.resolution | string | No | "1K" or "2K" (default: "1K") |
| input.aspect_ratio | string | No | Output aspect ratio |

Key features: Multi-reference consistency (up to 8 images), superior text rendering.

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "input": {
      "prompt": "A luxury watch on marble, studio lighting, commercial photography",
      "resolution": "2K",
      "aspect_ratio": "1:1"
    }
  }'
```

---

### Z Image

Model ID: `z-image-text-to-image`
Engine: Alibaba
Capabilities: Text to Image only
Resolution: 1024x1024 (fixed for 1:1)
Credits: 2

Parameters:
| Parameter | Type | Required | Values |
|-----------|------|----------|--------|
| model | string | Yes | "z-image-text-to-image" |
| input.prompt | string | Yes | Max 1000 chars |
| input.aspect_ratio | string | No | "1:1", "4:3", "3:4", "16:9", "9:16" (default: "1:1") |

Example:
```bash
curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-text-to-image",
    "input": {
      "prompt": "A serene mountain landscape at sunset, photorealistic",
      "aspect_ratio": "16:9"
    }
  }'
```

---

## Pricing

### Subscription Plans

| Plan | Monthly | Yearly | Credits/Month | API Access |
|------|---------|--------|---------------|-----------|
| Free | $0 | — | 60 (one-time) | No |
| Starter | $15/mo | $10/mo ($120/yr) | 500 | Yes (100 req/day) |
| Pro | $29.99/mo | $15/mo ($180/yr) | 2,500 | Yes (500 req/day) |

Pro plan scales up to 250,000 credits/mo ($1,749.99/mo or $1,205/mo yearly).

### One-Time Credit Packs (Non-Expiring)

| Credits | Price | Per Credit |
|---------|-------|-----------|
| 3,000 | $75 | $0.025 |
| 10,000 | $220 | $0.022 |
| 25,000 | $450 | $0.018 |
| 50,000 | $900 | $0.018 |
| 200,000 | $3,000 | $0.015 |

### All Features

| Feature | Free | Starter | Pro |
|---------|------|---------|-----|
| All models | Yes | Yes | Yes |
| Watermark | Yes | No | No |
| HD output | No | Yes | Yes |
| Parallel tasks | 1 | 2 | Unlimited |
| API access | No | Yes | Yes |
| Priority queue | No | No | Yes |

---

## Complete Integration Example

```javascript
const API_KEY = 'sk-your-api-key';
const BASE_URL = 'https://vicsee.com/api/v1';

// 1. Generate a video
const genResponse = await fetch(`${BASE_URL}/generate`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'veo-3-1-text-to-video',
    input: {
      prompt: 'A cozy coffee shop, barista steaming milk, jazz playing',
      aspect_ratio: '16:9',
    },
  }),
});
const { data: task } = await genResponse.json();
console.log(`Task ${task.id} created, ${task.creditsUsed} credits used`);

// 2. Poll for result
let result = null;
let delay = 2000;
while (!result) {
  await new Promise(r => setTimeout(r, delay));
  const pollResponse = await fetch(`${BASE_URL}/tasks/${task.id}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` },
  });
  const pollData = await pollResponse.json();
  if (pollData.data.status === 'completed') {
    result = pollData.data.result;
  } else if (pollData.data.status === 'failed') {
    throw new Error('Generation failed');
  }
  delay = Math.min(delay * 1.5, 10000);
}

console.log(`Video ready: ${result.url}`);

// 3. Check remaining credits
const creditsResponse = await fetch(`${BASE_URL}/credits`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` },
});
const { data: { credits } } = await creditsResponse.json();
console.log(`Remaining credits: ${credits}`);
```

---

## Polling Strategy

Recommended: Exponential backoff starting at 2 seconds, capping at 10 seconds.

- Video generation typically takes 30-120 seconds
- Image generation typically takes 5-30 seconds
- Max recommended polling attempts: 60

---

## Quick Model Selection Guide

Easiest start (video): VicSee 1.0 (28 credits, 8s 720p, one-click)
Easiest start (image): VicSee Image 1.0 (6 credits, one-click)
Best budget video: Sora 2 (20 credits for 10s 720p)
Best quality video: Veo 3.1 Quality (300 credits, up to 4K, native audio)
Best for dialogue: Kling 2.6 (lip-sync, audio-visual sync)
Best flexible duration: Kling 3.0 (3-15 seconds, per-second pricing)
Best multilingual: Seedance 1.5 Pro (8+ languages with audio)
Best budget image: Z Image (2 credits, photorealistic)
Best HD image: Nano Banana Pro (18 credits for 2K, 36 for 4K)
Best multi-reference: FLUX 2 (up to 8 reference images)
Best upscaling: Nano Banana Upscale (3 credits, 2x or 4x)