# Query User Balance
Source: https://docs.vidgo.ai/api-manual/account-management/user-balance
api-manual/account-management/user-balance.json GET /api/user/balance
Query the credit balance of your user account
# Query User Balance
Query the current credit balance of your user account in real-time.
## Use Cases
Show real-time account balance in your application dashboard
Set up notifications when credits fall below a threshold
Prompt users to top up credits before running out
Monitor credit consumption and track spending patterns
## Important Notes
**Real-time Balance**: The balance returned reflects your current credit amount at the time of the request.
**Rate Limiting**: Avoid excessive polling. Cache the balance and refresh only when necessary (e.g., after completing a generation task).
**Credit Deduction**: Credits are deducted only when generation tasks complete successfully. Failed tasks do not consume credits.
# Error Codes
Source: https://docs.vidgo.ai/api-manual/error-codes
API error codes and response formats
# Error Codes
This page documents all possible API response codes and error types.
## Response Format
### Success Response
When a request is successful, the API returns a response with `code: 200`:
```json theme={null}
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2025-11-12T10:30:00"
}
}
```
### Error Response
When an error occurs, the API returns a response with the corresponding error code:
```json theme={null}
{
"code": 400,
"error": {
"message": "task_id is required",
"type": "validation_error"
}
}
```
### Task Failed Response
When a task fails during processing, the response includes `status: "failed"` with an error message:
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "failed",
"files": [],
"created_time": "2025-11-25T08:50:13",
"error_message": "The prompt violates our content policy"
}
}
```
## Business Status Codes
### 200 - Success
Request completed successfully. Check the `status` field in the response to determine task state.
### 400 - Bad Request
The request contains invalid parameters or data.
| Type | Description |
| -------------------------- | ------------------------------ |
| `validation_error` | Parameter validation error |
| `content_moderation_error` | Content moderation error |
| `content_too_long_error` | Content exceeds maximum length |
| `file_format_error` | Invalid file format |
**Example:**
```json theme={null}
{
"code": 400,
"error": {
"message": "task_id is required",
"type": "validation_error"
}
}
```
### 402 - Payment Required
Insufficient account balance or credits.
| Type | Description |
| ---------------------------- | -------------------- |
| `insufficient_credits_error` | Insufficient credits |
**Example:**
```json theme={null}
{
"code": 402,
"error": {
"message": "Insufficient credits to complete this request",
"type": "insufficient_credits_error"
}
}
```
### 403 - Forbidden
Access denied due to permission restrictions.
| Type | Description |
| ------------------------- | ----------------- |
| `permission_denied_error` | Permission denied |
**Example:**
```json theme={null}
{
"code": 403,
"error": {
"message": "You do not have permission to access this resource",
"type": "permission_denied_error"
}
}
```
### 404 - Not Found
The requested resource does not exist.
| Type | Description |
| -------------------------- | ------------------ |
| `resource_not_found_error` | Resource not found |
**Example:**
```json theme={null}
{
"code": 404,
"error": {
"message": "Task not found",
"type": "resource_not_found_error"
}
}
```
### 408 - Request Timeout
The request took too long to process.
| Type | Description |
| --------------- | --------------- |
| `timeout_error` | Request timeout |
**Example:**
```json theme={null}
{
"code": 408,
"error": {
"message": "Request timed out",
"type": "timeout_error"
}
}
```
### 429 - Too Many Requests
Rate limit exceeded.
| Type | Description |
| ------------------ | ------------------- |
| `rate_limit_error` | Rate limit exceeded |
**Example:**
```json theme={null}
{
"code": 429,
"error": {
"message": "Rate limit exceeded. Please try again later.",
"type": "rate_limit_error"
}
}
```
### 500 - Internal Server Error
An unexpected server error occurred.
| Type | Description |
| ---------------- | --------------------- |
| `internal_error` | Internal server error |
**Example:**
```json theme={null}
{
"code": 500,
"error": {
"message": "An internal error occurred. Please try again later.",
"type": "internal_error"
}
}
```
### 502 - Bad Gateway
Upstream service error.
| Type | Description |
| ---------------- | ---------------------- |
| `upstream_error` | Upstream service error |
**Example:**
```json theme={null}
{
"code": 502,
"error": {
"message": "Upstream service unavailable",
"type": "upstream_error"
}
}
```
### 503 - Service Unavailable
The service is temporarily unavailable.
| Type | Description |
| --------------- | ------------------- |
| `service_error` | Service unavailable |
**Example:**
```json theme={null}
{
"code": 503,
"error": {
"message": "The server is busy. Please try again later.",
"type": "service_error"
}
}
```
## Error Handling Best Practices
**Implement retry logic**: For 500, 502, and 503 errors, implement exponential backoff retry logic.
**Handle rate limits**: When receiving 429 errors, wait before retrying. Consider implementing request queuing.
**Validate inputs**: Check your request parameters before sending to avoid 400 errors.
**Monitor credits**: Keep track of your credit balance to avoid 402 errors during critical operations.
# Upload File from Base64
Source: https://docs.vidgo.ai/api-manual/file-series/upload-base64
api-manual/file-series/upload-base64.json POST /api/common/upload/base64
Upload files to Vidgo API using Base64-encoded data or Data URL format
## Usage Guide
* This endpoint accepts Base64-encoded file data for upload to Vidgo API storage
* Supports both Data URL format (with MIME type prefix) and pure Base64 strings
* Ideal for uploading files that are already Base64-encoded in your application, such as canvas drawings or client-side image manipulations
* Files are immediately accessible via the returned URL and remain available for 72 hours
## Parameter Details
* **Base64 Data Format**:
* **Data URL format**: `data:image/png;base64,iVBORw0KGgo...` (recommended)
* **Pure Base64 string**: `iVBORw0KGgo...` (without MIME type prefix)
* The Base64 string must not contain any whitespace, newline characters, or formatting
* Supported file formats: **JPEG, PNG, GIF, WebP** only
* Maximum upload limit: **1 image per request**
* **Storage Configuration**:
* All files are automatically stored with a `temp/` prefix in the storage path
* If you specify `upload_path: "profile-images"`, the actual path will be `temp/profile-images`
* Files will expire and be automatically deleted **72 hours** after upload
* **File Naming**:
* If `file_name` is not provided, the system generates a unique name in the format: `{timestamp}_{random}_{extension}`
* Example auto-generated name: `20251229130857_a8B9cD2e.png`
## Developer Notes
* When to use Base64 upload:
* Client-side generated images (canvas, screenshots)
* Images already encoded in Base64 format in your application
* Small to medium-sized images where encoding overhead is acceptable
* When NOT to use Base64 upload:
* Large image files (Base64 encoding increases size by \~33%)
* Files stored on disk (use stream upload instead)
* Files available via URL (use URL upload instead)
* Ensure your Base64 data is properly formatted without any line breaks or spaces
* For persistent storage needs, download and save the file locally before the 72-hour expiration
## Rate Limits and Quotas
* **Rate Limit**: 5 requests per minute per API key
* When the rate limit is exceeded, you will receive a `429 Too Many Requests` error
* Implement exponential backoff retry logic for handling rate limit errors
## Common Error Scenarios
* **Invalid Base64 Encoding**: The provided Base64 string cannot be decoded
* **Invalid Data URL Format**: The Data URL format is malformed (e.g., missing `data:` prefix or `;base64,` separator)
* **Unsupported File Type**: The decoded file is not in a supported image format (JPEG, PNG, GIF, WebP)
* **Invalid File Data**: The decoded data is empty or corrupted
* **Authentication Error**: Missing or invalid API key in the Authorization header
# Upload File Stream
Source: https://docs.vidgo.ai/api-manual/file-series/upload-stream
api-manual/file-series/upload-stream.json POST /api/common/upload/stream
Upload files to Vidgo API using multipart/form-data format for direct file uploads
## Usage Guide
* This endpoint enables direct file uploads using the standard `multipart/form-data` format
* Supports uploading files directly from local storage with automatic file type identification
* Best suited for local file uploads from desktop applications, mobile apps, or web forms
* Files are immediately accessible via the returned URL and remain available for 72 hours
## Parameter Details
* **File Upload Requirement**:
* The `file` field must contain binary file data
* Supported file formats: **JPEG, PNG, GIF, WebP** only
* Maximum upload limit: **1 image per request**
* The system automatically identifies the file type from the binary data
* **Parameter Naming Convention**:
* This endpoint supports both **snake\_case** and **camelCase** naming conventions
* `upload_path` or `uploadPath` - both are accepted
* `file_name` or `fileName` - both are accepted
* Use whichever convention matches your application's coding style
* **Storage Configuration**:
* All files are automatically stored with a `temp/` prefix in the storage path
* If you specify `upload_path: "photos"`, the actual path will be `temp/photos`
* Files will expire and be automatically deleted **72 hours** after upload
* **File Naming**:
* If `file_name` is not provided, the system generates a unique name in the format: `{timestamp}_{random}_{extension}`
* Example auto-generated name: `20251229130857_a8B9cD2e.png`
## Developer Notes
* When to use file stream upload:
* Direct file uploads from user's local storage
* Form-based file uploads from web applications
* Mobile app file uploads
* Server-to-server file transfers
* This is the most efficient upload method for files already stored on disk
* The multipart/form-data format is standard across all programming languages and HTTP clients
* For persistent storage needs, download and save the file locally before the 72-hour expiration
## Rate Limits and Quotas
* **Rate Limit**: 5 requests per minute per API key
* When the rate limit is exceeded, you will receive a `429 Too Many Requests` error
* Implement exponential backoff retry logic for handling rate limit errors
## Common Error Scenarios
* **Missing File**: No file was provided in the request body (422 error)
* **Unsupported File Type**: The uploaded file is not in a supported image format (JPEG, PNG, GIF, WebP)
* **Empty File**: The uploaded file has zero bytes or is corrupted
* **Authentication Error**: Missing or invalid API key in the Authorization header
## Example Usage
### cURL Example
```bash theme={null}
curl -X POST "https://api.vidgo.ai/api/common/upload/stream" \
-H "Authorization: Bearer VIDGO_API_KEY" \
-F "file=@/path/to/image.png" \
-F "file_name=my-image.png"
```
### Python Example
```python theme={null}
import requests
url = "https://api.vidgo.ai/api/common/upload/stream"
headers = {"Authorization": "Bearer VIDGO_API_KEY"}
files = {"file": open("/path/to/image.png", "rb")}
data = {"file_name": "my-image.png"}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```
### JavaScript Example (Node.js)
```javascript theme={null}
const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');
const form = new FormData();
form.append('file', fs.createReadStream('/path/to/image.png'));
form.append('file_name', 'my-image.png');
axios.post('https://api.vidgo.ai/api/common/upload/stream', form, {
headers: {
'Authorization': 'Bearer VIDGO_API_KEY',
...form.getHeaders()
}
})
.then(response => console.log(response.data))
.catch(error => console.error(error));
```
# Upload File from URL
Source: https://docs.vidgo.ai/api-manual/file-series/upload-url
api-manual/file-series/upload-url.json POST /api/common/upload/url
Upload files to Vidgo API by providing a remote URL
## Usage Guide
* This endpoint enables uploading files to Vidgo API by providing a remote URL
* The system automatically downloads the file from the specified URL and stores it in Vidgo API storage
* Ideal for migrating files from external servers or integrating with third-party file sources
* Files are returned with a direct access URL and remain available for 72 hours
## Parameter Details
* **File URL Requirement**:
* The `file_url` must be a publicly accessible URL using HTTP or HTTPS protocol
* The remote server must allow the file to be downloaded without authentication
* Supported file formats: **JPEG, PNG, GIF, WebP** only
* Maximum upload limit: **1 image per request**
* **Storage Configuration**:
* All files are automatically stored with a `temp/` prefix in the storage path
* If you specify `upload_path: "avatars"`, the actual path will be `temp/avatars`
* Files will expire and be automatically deleted **72 hours** after upload
* **File Naming**:
* If `file_name` is not provided, the system generates a unique name in the format: `{timestamp}_{random}_{extension}`
* Example auto-generated name: `20251229130857_a8B9cD2e.png`
## Developer Notes
* Ensure your source URL is publicly accessible and does not require authentication or special headers
* The download process may take a few seconds depending on the file size and network conditions
* For persistent storage needs, download and save the file locally before the 72-hour expiration
* The `file_url` and `download_url` in the response are identical and both provide direct access to the uploaded file
## Rate Limits and Quotas
* **Rate Limit**: 5 requests per minute per API key
* When the rate limit is exceeded, you will receive a `429 Too Many Requests` error
* Implement exponential backoff retry logic for handling rate limit errors
## Common Error Scenarios
* **Invalid URL**: The provided URL is malformed or unreachable
* **Download Failure**: Network timeout or connection issues when downloading from the remote URL
* **Unsupported File Type**: The file at the URL is not in a supported image format (JPEG, PNG, GIF, WebP)
* **Authentication Error**: Missing or invalid API key in the Authorization header
# Flux.2 Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/flux-2
api-manual/image-series/flux-2.json POST /api/generate/submit
32B parameter image generation model from Black Forest Labs with multi-reference support and superior text rendering
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Flux 2 Image Generation
FLUX.2 is a 32 billion parameter image generation and editing model from Black Forest Labs. It combines text-to-image and multi-image editing in a single architecture, delivering photoreal images with clean typography at resolutions up to 2K. Supports referencing up to 8 images simultaneously with excellent character, product, and style consistency.
## Available Models
* **flux-2-pro** - High-fidelity text-to-image generation for production deployments
* **flux-2-pro-edit** - Advanced multi-reference image editing with up to 8 input images
* **flux-2-flex** - Adjustable speed vs. quality balance for flexible workflows
* **flux-2-flex-edit** - Flexible image editing with multi-reference support
# Flux Kontext Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/flux-kontext
api-manual/image-series/flux-kontext.json POST /api/generate/submit
Image generation and image editing models powered by Black Forest Labs Flux Kontext
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Flux Kontext Image Generation
Flux Kontext is powered by Black Forest Labs. It supports both text-to-image generation and image editing through the same unified submit endpoint.
## Available Models
* **flux-kontext-pro** - Flux Kontext Pro text-to-image generation
* **flux-kontext-pro-edit** - Flux Kontext Pro image editing, `image_urls` is required
* **flux-kontext-max** - Flux Kontext Max text-to-image generation
* **flux-kontext-max-edit** - Flux Kontext Max image editing, `image_urls` is required
## Notes
* `size` supports `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`, `9:21`
* `output_format` supports `png`, `jpg`
* `image_urls` is required for edit models
* Only `image_urls[0]` is used as the input image
* Other downstream fields are not exposed in the current API and use system defaults
* Credits are charged directly according to the configured model price
# GPT-4o Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/gpt-4o-image
api-manual/image-series/gpt-4o-image.json POST /api/generate/submit
High-quality image generation and editing with GPT-4o
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# GPT-4o Image Generation
Generate high-quality images using OpenAI's GPT-4o model. Supports text-to-image, image-to-image, and advanced image editing capabilities.
## Available Models
* **gpt-4o-image** - Text-to-image and image-to-image generation
* **gpt-4o-image-edit** - Advanced image editing with mask support
# GPT Image 1.5 Generation
Source: https://docs.vidgo.ai/api-manual/image-series/gpt-image-1.5
api-manual/image-series/gpt-image-1.5.json POST /api/generate/submit
High-quality image generation and editing with GPT Image 1.5
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# GPT Image 1.5 Generation
Generate high-quality images using GPT Image 1.5 models. Supports text-to-image, image-to-image, and advanced image editing capabilities.
## Available Models
* **gpt-image-1.5** - Text-to-image and image-to-image generation
* **gpt-image-1.5-edit** - Advanced image editing with mask support
# GPT Image 2 Generation
Source: https://docs.vidgo.ai/api-manual/image-series/gpt-image-2
api-manual/image-series/gpt-image-2.json POST /api/generate/submit
Generate and edit images with GPT Image 2
1. After submission, a `task_id` is returned. If you provide a `callback_url`, Vidgo API sends a POST request when the task becomes `finished` or `failed`.
2. You can always retrieve the result with the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# GPT Image 2 Generation
## Overview
Use Vidgo API to generate a single image from a prompt or edit one or more reference images with natural-language instructions. GPT Image 2 supports explicit quality tiers, ratio presets, custom dimensions, and `1K`, `2K`, or `4K` resolution control.
## Available Models
* **gpt-image-2** - Text-to-image generation from a prompt.
* **gpt-image-2-edit** - Image editing based on one or more `image_urls` and a text instruction.
## Notes
* `input.prompt` is required and supports up to `4000` characters.
* `input.quality` is optional: `low`, `medium`, or `high`. Default: `low`.
* `input.size` is optional. Supported values are `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `16:9`, `9:16`, `21:9`, or a custom `WIDTHxHEIGHT` value.
* `input.resolution` is optional: `1K`, `2K`, or `4K`.
* `gpt-image-2-edit` requires `input.image_urls`.
* `gpt-image-2` does not accept `input.image_urls`.
* Each request returns one image.
* `n` is not supported for GPT Image 2 requests.
## Resolution
The `resolution` parameter controls the effective output resolution and credits cost.
| Resolution | Credits multiplier | Description |
| ---------- | -----------------: | ------------------------------------------------- |
| `1K` | 1x | Standard resolution |
| `2K` | 2x | High resolution |
| `4K` | 4x | Ultra-high resolution for true 4K-supported sizes |
### Billing by Quality
| Quality | 1K | 2K | 4K |
| ------- | ---------: | ---------: | ---------: |
| Low | 2 credits | 4 credits | 8 credits |
| Medium | 3 credits | 6 credits | 12 credits |
| High | 12 credits | 24 credits | 48 credits |
## Resolution Rules
* If `size` is omitted or set to `auto`, the request is processed and billed as `1K`, even if `resolution` is provided.
* Custom `WIDTHxHEIGHT` sizes require `resolution` `2K` or `4K`.
* `4K` billing applies only to `16:9`, `9:16`, `21:9`, or custom sizes with a `3840`-pixel edge.
* A `4K` request that does not meet the true 4K rule is billed at the effective `2K` tier.
* A custom size whose longest edge is `3840` must use `resolution: "4K"`.
## Custom Size Constraints
Custom sizes use `WIDTHxHEIGHT` format, for example `2304x1536`, and must satisfy all of the following:
* Width and height must both be divisible by `16`.
* The maximum edge length is `3840` pixels.
* The aspect ratio must not exceed `3:1`.
* Total pixel count must stay between `655,360` and `8,294,400`.
## Request Examples
````bash theme={null}
### Generate Image
```bash
curl --request POST \
--url https://api.vidgo.ai/api/generate/submit \
--header "Authorization: Bearer VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "gpt-image-2",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A premium product photo of a silver espresso machine on a clean white studio background, realistic lighting, high detail",
"quality": "low",
"size": "1:1",
"resolution": "1K"
}
}'
````
### Edit Image
```bash theme={null}
curl --request POST \
--url https://api.vidgo.ai/api/generate/submit \
--header "Authorization: Bearer VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "gpt-image-2-edit",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Replace the background with a clean white studio backdrop and add a soft natural shadow while preserving the product shape",
"quality": "medium",
"size": "1:1",
"resolution": "2K",
"image_urls": [
"https://example.com/reference-product.jpg"
]
}
}'
```
## Response Flow
The submit endpoint returns a `task_id`, `status`, and `created_time`. If you provide `callback_url`, Vidgo API sends a POST request when the task reaches `finished` or `failed`.
Use the unified status endpoint to retrieve the final result:
```bash theme={null}
curl --request GET \
--url https://api.vidgo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \
--header "Authorization: Bearer VIDGO_API_KEY"
```
When the task is `finished`, the status response includes generated image file URLs in `data.files`. If the task fails, the status payload returns the failure details for troubleshooting.
# Grok Imagine Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/grok-imagine-image
api-manual/image-series/grok-imagine-image.json POST /api/generate/submit
High-quality image generation with Grok Imagine
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Grok Imagine Image Generation
Generate high-quality images using the Grok Imagine model. Supports text-to-image and image-to-image generation with optional aspect ratios.
`input.size` is optional. Supported values: `2:3`, `3:2`, `1:1`, `9:16`, `16:9`.
For image-to-image, `input.image_urls` is required.
`array(URL)`
An array containing a single URL string pointing to the reference image.
Please provide the URL of the uploaded file; Accepted types: image/jpeg, image/png, image/webp; Max size: 10.0MB.
## Available Models
* **grok-imagine-image** - Text-to-image and image-to-image generation
# Nano Banana Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/nano-banana
api-manual/image-series/nano-banana.json POST /api/generate/submit
Fast image generation powered by Gemini 2.5 Flash
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Nano Banana Image Generation
Fast and efficient image generation powered by Google's Gemini 2.5 Flash model. Ideal for quick iterations and high-throughput applications.
## Available Models
* **nano-banana** - Text-to-image and image-to-image generation
* **nano-banana-edit** - Advanced image editing capabilities
# Nano Banana Pro(Nano Banana 2) Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/nano-banana-2
api-manual/image-series/nano-banana-2.json POST /api/generate/submit
Next-generation AI image generation powered by Gemini 3 Pro Image Preview
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Nano Banana Pro(Nano Banana 2) Image Generation
Next-generation AI image generation powered by Google's Gemini 3 Pro Image Preview. Delivers 2K native resolution images in under 1 second with enhanced text rendering, character consistency, and designer-grade quality.
## Available Models
* **nano-banana-2** - Text-to-image and image-to-image generation
* **nano-banana-2-edit** - Advanced image editing capabilities
# Nano Banana 2 (gemini-3.1-flash-image-preview) Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/nano-banana-2-new
api-manual/image-series/nano-banana-2-new.json POST /api/generate/submit
Next-generation AI image generation powered by Gemini 3.1 Flash Image Preview
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Nano Banana 2 (gemini-3.1-flash-image-preview) Image Generation
Next-generation AI image generation powered by Google's Gemini 3.1 Flash Image Preview. Delivers native 2K / 4K resolution images with precise multilingual text rendering, chain-of-thought understanding of physical relationships, and support for up to 14 reference images.
## Available Models
* **nano-banana-2-new** - Text-to-image and image-to-image generation
* **nano-banana-2-new-edit** - Advanced image editing capabilities
# Seedream-4 Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/seedream-4
api-manual/image-series/seedream-4.json POST /api/generate/submit
Image generation model powered by ByteDance Seedream-4 with support for text-to-image and image editing
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Seedream-4 Image Generation
Seedream-4 is powered by ByteDance Seedream-4. It supports both text-to-image generation and image editing through the same unified submit endpoint.
## Available Models
* **seedream-4** - Text-to-image generation, optionally with reference images
* **seedream-4-edit** - Image editing mode. `image_urls` is required
## Notes
* `size` maps to aspect ratio and supports `1:1`, `3:4`, `4:3`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`
* `resolution` supports `1K`, `2K`, `4K`, with default `2K`
* `n` supports `1-15`
* The total of `image_urls` plus `n` must not exceed `15`
* Credits are pre-deducted as `base credits * n`. If fewer images are returned than requested, the unused portion is refunded automatically
# Seedream-4.5 Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/seedream-4-5
api-manual/image-series/seedream-4-5.json POST /api/generate/submit
Advanced image generation model with support for text-to-image, image-to-image, and multi-image reference capabilities
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Seedream-4.5 Image Generation
Seedream-4.5 is an advanced image generation model that supports text-to-image, image-to-image, and image editing with multi-reference capabilities. It delivers high-quality images with flexible aspect ratios and prompt optimization options.
## Available Models
* **seedream-4.5** - High-quality text-to-image and image-to-image generation
* **seedream-4.5-edit** - Advanced image editing with multi-image reference support (up to 10 images)
# Seedream-5.0-Lite Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/seedream-5-0-lite
api-manual/image-series/seedream-5-0-lite.json POST /api/generate/submit
Seedream 5.0 Lite image generation and editing with preset sizes, custom dimensions, and up to 10 reference images
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Seedream-5.0-Lite Image Generation
Seedream-5.0-Lite is an image generation and editing model for async production workflows. It supports text-to-image, reference-based editing, flexible preset sizes, and custom dimensions through the same unified Vidgo API submit and status endpoints.
## Available Models
* **seedream-5.0-lite** - Text-to-image and image-to-image generation with preset or custom output sizes
* **seedream-5.0-lite-edit** - Image editing with 1 to 10 JPEG or PNG reference images
## Request Notes
* `model` must be `seedream-5.0-lite` or `seedream-5.0-lite-edit`
* `input.prompt` is required and supports up to 2000 characters
* `input.n` accepts integers from `1` to `15`
* `input.image_urls` is optional for `seedream-5.0-lite` image-to-image requests and required for `seedream-5.0-lite-edit`; both accept `1` to `10` URLs
* successful submit responses return `task_id` and `created_time`; query final task state through the unified status endpoint
## Size Parameter
`input.size` supports four accepted forms:
1. Resolution presets such as `2K` and `3K`
2. Ratio presets such as `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, and `21:9`
3. Custom size strings such as `2304x1728`
4. Structured JSON objects such as `{ "width": 2304, "height": 1728 }`
Object-style `size` is supported for both `seedream-5.0-lite` and `seedream-5.0-lite-edit`.
Use preset sizes when you want quick resolution or aspect-ratio control. Use custom strings or objects when your workflow needs exact dimensions.
## Custom Size Example
```json theme={null}
{
"model": "seedream-5.0-lite",
"input": {
"prompt": "A cinematic bookstore interior with clean bilingual signage and soft blue-hour light",
"size": {
"width": 2304,
"height": 1728
},
"n": 1
}
}
```
## Edit Mode Example
```json theme={null}
{
"model": "seedream-5.0-lite-edit",
"input": {
"prompt": "Keep the composition and convert the scene into a snowy evening with warmer storefront light",
"image_urls": [
"https://example.com/reference1.jpg",
"https://example.com/reference2.jpg"
],
"size": "2304x1728",
"n": 1
}
}
```
## Error Response Shape
Validation and authentication failures follow the unified Vidgo API error shape:
```json theme={null}
{
"detail": "prompt is required"
}
```
# Z-Image Generation
Source: https://docs.vidgo.ai/api-manual/image-series/z-image
api-manual/image-series/z-image.json POST /api/generate/submit
High-quality image generation with Z-Image
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Z-Image Generation
Generate high-quality images using the Z-Image model. Supports text-to-image generation with flexible aspect ratios.
## Available Models
* **z-image** - Text-to-image generation
# Add Instrumental
Source: https://docs.vidgo.ai/api-manual/music-series/add-instrumental
api-manual/music-series/add-instrumental.json POST /api/generate/submit
Generate musical accompaniment for uploaded audio files
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint generates musical accompaniment for uploaded audio files
* Typically used with vocal stems or melodies to create backing tracks
* Perfect for adding instrumental layers to existing recordings without needing a producer
## Parameter Details
* Required parameters:
* `upload_url`: URL of the audio file to process
* `title`: Name for the generated track
* `tags`: Desired musical styles (e.g., "relaxing, piano, soothing")
* `negative_tags`: Styles to exclude (e.g., "heavy metal, fast drums")
* Model selection:
* **V5**: Superior musical expressiveness with faster generation
* **V4\_5PLUS**: Enhanced tonal richness (default)
## Developer Notes
* Use descriptive tags to guide the style of the instrumental
* Combine positive and negative tags for precise control over the output
* The callback mechanism sends notifications at three stages: text generation, first track completion, and all tracks completed
## Optional parameters
* `model` (string): AI model version. Options: `V4_5PLUS` (default), `V5`.
* `vocal_gender` (string): Vocal gender preference. Use `m` for male, `f` for female. Note: This parameter can only increase the probability but cannot guarantee the specified gender.
* `style_weight` (number): Strength of adherence to style. Range 0-1, up to 2 decimals.
* `weirdness_constraint` (number): Controls creative deviation. Range 0-1, up to 2 decimals.
* `audio_weight` (number): Balance weight for audio features. Range 0-1, up to 2 decimals.
# Add Vocals
Source: https://docs.vidgo.ai/api-manual/music-series/add-vocals
api-manual/music-series/add-vocals.json POST /api/generate/submit
Layer AI-generated vocals on top of an existing instrumental
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint adds AI-generated vocals to an existing instrumental track
* Upload an instrumental file and provide lyrics or a description for the vocals
* Perfect for transforming instrumental tracks into complete songs
## Parameter Details
* Required parameters:
* `upload_url`: URL of the instrumental audio file
* `prompt`: Lyrics or description for the vocals
* `title`: Name for the generated track
* `style`: Music style to guide vocal delivery
* `negative_tags`: Styles to exclude from generation
* Model selection:
* **V5**: Superior musical expressiveness with faster generation
* **V4\_5PLUS**: Enhanced tonal richness (default)
## Developer Notes
* The `prompt` parameter serves as both lyrics and creative direction for the vocals
* Use `style` to specify the vocal delivery style (e.g., "Pop Ballad", "Rock", "R\&B")
* Combine with `vocal_gender` for more control over the vocal output
## Optional parameters
* `model` (string): AI model version. Options: `V4_5PLUS` (default), `V5`.
* `vocal_gender` (string): Vocal gender preference. Use `m` for male, `f` for female. Note: This parameter can only increase the probability but cannot guarantee the specified gender.
* `style_weight` (number): Strength of adherence to style. Range 0-1, up to 2 decimals.
* `weirdness_constraint` (number): Controls creative deviation. Range 0-1, up to 2 decimals.
* `audio_weight` (number): Balance weight for audio features. Range 0-1, up to 2 decimals.
# Boost Music Style
Source: https://docs.vidgo.ai/api-manual/music-series/boost-music-style
api-manual/music-series/boost-music-style.json POST /api/generate/submit
Generate enhanced music style descriptions using AI
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint generates enhanced music style descriptions based on your input
* Provide concise keywords describing genre, mood, or musical characteristics
* The AI will expand and enrich your style description for better music generation results
## Parameter Details
* `content` (required): A brief description of the desired music style
* Use comma-separated keywords for best results
* Include genre (Pop, Jazz, Rock), mood (Mysterious, Upbeat), or instruments (Piano, Guitar)
## Developer Notes
* Use the generated style descriptions with the Generate Music endpoint for better results
* Keep input descriptions concise and clear for optimal enhancement
# Convert to WAV
Source: https://docs.vidgo.ai/api-manual/music-series/convert-to-wav
api-manual/music-series/convert-to-wav.json POST /api/generate/submit
Convert generated music tracks to high-quality WAV format
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint converts generated music tracks to high-quality WAV format
* WAV files provide lossless audio quality for professional use
* The download URL for the WAV file is delivered via the callback
## Parameter Details
* `task_id` (required): Task ID from a completed music generation (Generate Music or Extend Music)
* `audio_id` (required): Specific audio track identifier from the callback data
## Developer Notes
* Each audio track can only be converted to WAV once
* The callback will include a download URL for the high-quality WAV file
* WAV files are significantly larger than compressed formats - plan storage accordingly
# Create Music Video
Source: https://docs.vidgo.ai/api-manual/music-series/create-music-video
api-manual/music-series/create-music-video.json POST /api/generate/submit
Generate visualized music videos from audio tracks
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint generates visualized music videos from audio tracks
* Creates MP4 videos with audio visualization and optional branding
* Useful for social media content, promotional materials, or music sharing
## Parameter Details
* `task_id` (required): Task ID from a completed music generation (Generate Music or Extend Music)
* `audio_id` (required): Specific audio track identifier from the callback data
## Developer Notes
* Each audio track can only have one music video generated
* If a video already exists, the API returns error code 409
* The callback includes a download URL for the generated MP4 video
* Video generation may take longer than audio processing tasks
## Optional parameters
* `author` (string): Artist or creator name displayed on the video cover. Maximum 50 characters.
* `domain_name` (string): Website or brand watermark displayed at the bottom of the video. Maximum 50 characters.
# Extend Music
Source: https://docs.vidgo.ai/api-manual/music-series/extend-music
api-manual/music-series/extend-music.json POST /api/generate/submit
Extend or modify existing music by creating a continuation based on a source audio track
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint extends an existing audio track from a specified point
* You can customize the extension with new style, prompt, and title, or inherit from the original track
* Use `default_param_flag` to control whether to use custom parameters or original track settings
## Parameter Details
* In Custom Mode ( `default_param_flag: true` ):
* `prompt`, `style`, `title`, and `continue_at` are **required**
* `continue_at` specifies the timestamp (in seconds) where extension begins
* Character limits vary by model:
* **V4**: `prompt` 3000 characters, `style` 200 characters, `title` 80 characters
* **V4\_5 & V4\_5PLUS**: `prompt` 5000 characters, `style` 1000 characters, `title` 100 characters
* **V4\_5ALL**: `prompt` 5000 characters, `style` 1000 characters, `title` 80 characters
* **V5**: `prompt` 5000 characters, `style` 1000 characters, `title` 100 characters
* In Simple Mode ( `default_param_flag: false` ):
* Only `audio_id` and `mv` are required
## Developer Notes
* Ensure you have a valid `audio_id` from a previously generated track before using this endpoint
* The extension will seamlessly continue from the specified `continue_at` timestamp
## Optional parameters
* `negative_tags` (string): Music styles or characteristics to exclude from the extension.
* `vocal_gender` (string): Vocal gender preference. Use `m` for male, `f` for female. Note: This parameter increases the probability but cannot guarantee adherence.
* `style_weight` (number): Strength of adherence to style. Range 0-1, up to 2 decimals.
* `weirdness_constraint` (number): Controls creative deviation. Range 0-1, up to 2 decimals.
* `audio_weight` (number): Balance weight for audio features. Range 0-1, up to 2 decimals.
* `persona_id` (string): Persona ID to apply to the extended music. How to generate persona\_id, visit [generate-persona](/api-manual/music-series/generate-persona).
# Generate Lyrics
Source: https://docs.vidgo.ai/api-manual/music-series/generate-lyrics
api-manual/music-series/generate-lyrics.json POST /api/generate/submit
AI-powered lyrics generation based on themes and descriptions
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint generates song lyrics based on your theme or description
* Multiple lyric variations may be generated for each request
* Use the generated lyrics with the Generate Music endpoint in Custom Mode
## Parameter Details
* `prompt` (required): Description of the desired lyrics content
* Be specific about theme, mood, style, or story elements
* Maximum length: 200 words
* Include details like genre feel, emotional tone, and narrative elements
# Generate Music
Source: https://docs.vidgo.ai/api-manual/music-series/generate-music
api-manual/music-series/generate-music.json POST /api/generate/submit
AI-powered music generation with customizable styles and vocals
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint creates music based on your text prompt
* Multiple variations will be generated for each request
* You can control detail level with custom mode and instrumental settings
## Parameter Details
* In Custom Mode ( `custom_mode: true` ):
* If `instrumental: true` : `style` and `title` are required
* If `instrumental: false` : `style`, `prompt`, and `title` are required
* Character limits vary by model:
* **V4**: `prompt` 3000 characters, `style` 200 characters
* **V4\_5 & V4\_5PLUS**: `prompt` 5000 characters, `style` 1000 characters
* **V4\_5ALL**: `prompt` 5000 characters, `style` 1000 characters
* **V5**: `prompt` 5000 characters, `style` 1000 characters
* `title` length limit: 80 characters (all models)
* In Non-custom Mode ( `custom_mode: false` ):
* `prompt` length limit: 500 characters
* Other parameters should be left empty
## Developer Notes
* Recommendation for new users: Start with `custom_mode: false` for simpler usage
## Optional parameters
* `vocal_gender` (string): Vocal gender preference. Use `m` for male, `f` for female. Note: This parameter is only effective when `custom_mode` is `true` . Based on practice, this parameter can only increase the probability but cannot guarantee adherence to male/female voice instructions.
* `style_weight` (number): Strength of adherence to style. Range 0-1, up to 2 decimals. Example: `0.65` .
* `weirdness_constraint` (number): Controls creative deviation. Range 0-1, up to 2 decimals. Example: `0.65` .
* `audio_weight` (number): Balance weight for audio features. Range 0-1, up to 2 decimals. Example: `0.65` .
* `persona_id` (string): Persona ID to apply to the generated music. Use this to apply a specific persona style to your music generation. Only available when Custom Mode is enabled. How to generate persona\_id, visit [generate-persona](/api-manual/music-series/generate-persona).
# Generate Music Cover
Source: https://docs.vidgo.ai/api-manual/music-series/generate-music-cover
api-manual/music-series/generate-music-cover.json POST /api/generate/submit
Create cover images for generated music.
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint creates a cover version of an existing music track
* Requires a valid task\_id from a previously generated music task
* The cover will be a new interpretation of the original track
## Parameter Details
* `task_id` (required): The task ID from a completed music generation task
* Must be a valid task\_id returned from the Generate Music or Extend Music endpoints
* The original task must have completed successfully
## Developer Notes
* A cover can only be generated once per original task
* Results are delivered via the callback URL when processing is complete
# Generate Persona
Source: https://docs.vidgo.ai/api-manual/music-series/generate-persona
api-manual/music-series/generate-persona.json POST /api/generate/submit
Create reusable musical personas from existing audio tracks
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint creates a reusable musical persona from an existing audio track
* Personas capture the vocal style, genre characteristics, and musical personality
* Once created, personas can be used with the Generate Music endpoint via the `persona_id` parameter
## Parameter Details
* `task_id` (required): Task ID from a completed music generation ([Generate](/api-manual/music-series/generate-music), [Extend](/api-manual/music-series/extend-music), [Upload Cover](/api-manual/music-series/upload-and-cover-audio), or [Upload Extend](/api-manual/music-series/upload-and-extend-audio))
* `audio_id` (required): Specific audio track identifier from the callback data
* `name` (required): A descriptive name that captures the musical style or character
* `description` (required): Detailed description including:
* Genre and mood
* Instrumentation preferences
* Vocal characteristics
* Unique musical personality traits
## Developer Notes
* Each audio track can only have one persona created from it
* If a persona already exists for the audio, the API returns error code 409
* You can apply the `persona_id` to the following endpoints:
* [Generate Music](/api-manual/music-series/generate-music)
* [Extend Music](/api-manual/music-series/extend-music)
* [Upload And Cover Audio](/api-manual/music-series/upload-and-cover-audio)
* [Upload And Extend Audio](/api-manual/music-series/upload-and-extend-audio)
* Provide detailed descriptions for best results when using the persona
# Get Timestamped Lyrics
Source: https://docs.vidgo.ai/api-manual/music-series/get-timestamped-lyrics
api-manual/music-series/get-timestamped-lyrics.json POST /api/generate/submit
Retrieve synchronized lyrics with precise timestamps
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint retrieves synchronized lyrics with precise timestamps for generated audio tracks
* Use this to create karaoke-style displays, subtitles, or lyric visualizations
* Requires a completed music generation task with vocals
## Parameter Details
* Required parameters:
* `task_id`: The unique identifier from a previous music generation task
* `audio_id`: The specific audio track identifier from the task result
* Both identifiers are obtained from the response of music generation endpoints or their callbacks
## Developer Notes
* This endpoint only works with audio tracks that contain vocals
* The `hoot_cer` (Character Error Rate) value indicates alignment precision - lower values mean better accuracy
* Use `waveform_data` for creating audio visualizations alongside the lyrics
## Response Fields
* `aligned_words` (array): List of lyric words with timing information
* `word` (string): The lyric text, may include section markers like `[Verse]`, `[Chorus]`
* `start_s` (number): Word start time in seconds
* `end_s` (number): Word end time in seconds
* `success` (boolean): Whether the word was successfully aligned
* `palign` (number): Alignment confidence score
* `waveform_data` (array): Numerical data for audio waveform visualization
* `hoot_cer` (number): Alignment precision score (Character Error Rate)
* `is_streamed` (boolean): Indicates if the audio is a streamed track
# Music Webhook
Source: https://docs.vidgo.ai/api-manual/music-series/music-webhook
Receive automatic callback notifications when music generation tasks complete
# Music Webhook Callbacks
Instead of polling the [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint, you can provide a `callback_url` when submitting music generation tasks to receive automatic notifications when generation completes.
## How It Works
1. **Submit with callback URL**: Include a `callback_url` parameter in your music generation request
2. **Task processing**: Vidgo API processes your music generation task
3. **Receive notification**: When the task status becomes `finished` or `failed`, Vidgo API sends a POST request to your callback URL
4. **Process result**: Your server receives the complete task data including generated files
## Callback Request
When a task completes, Vidgo API will send a POST request to your callback URL:
### Request Headers
```
Content-Type: application/json
```
### Request Body Structure
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [...],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
The `files` array content varies depending on which model created the task. See [Response Fields](#response-fields-files-data) below for details.
## Response Fields (files data)
The `files` array content varies depending on which model created the task.
| Model | Field | Type | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ------------- | -------------------------------------------------------------------------------------- |
| `generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section` | `audio_id` | string | Unique identifier for the audio file |
| 閳? | `audio_url` | string | Direct download URL for the audio file |
| 閳? | `image_url` | string | Cover image URL |
| 閳? | `title` | string | Track title |
| 閳? | `tags` | string | Style tags |
| 閳? | `duration` | number | Audio duration in seconds |
| 閳? | `prompt` | string | Generation prompt used |
| `get-timestamped-lyrics` | `timestampe_lyrics` | string | Lyrics with timestamps |
| `generate-lyrics` | `title` | string | Lyrics title |
| 閳? | `text` | string | Complete lyrics content |
| `boost-music-style` | `style` | string | Enhanced music style |
| `convert-to-wav` | `wav_url` | string | URL to converted WAV file |
| `separate-vocals` | `separate_vocals` | string (JSON) | JSON string containing separated audio URLs. [See details](#separate-vocals) |
| `upload-and-separate-vocals` | `vocal_removal` | string (JSON) | JSON string containing separated stem URLs. [See details](#upload-and-separate-vocals) |
| `stem-split` | `stem_split` | string (JSON) | JSON string containing full stem separation URLs. [See details](#stem-split) |
| `generate-music-cover` | `generate_cover` | string (JSON) | JSON string containing generated cover images. [See details](#generate-music-cover) |
| `generate-persona` | `persona_id` | string | Generated persona identifier |
| `create-music-video` | `video_url` | string | Generated video URL |
### JSON Field Details
#### separate-vocals
`separate_vocals` fields:
* `vocal_url` - URL to the extracted vocal track
* `instrumental_url` - URL to the instrumental track
#### upload-and-separate-vocals
`vocal_removal` fields:
* `bass` - URL to the bass track
* `drums` - URL to the drums track
* `piano` - URL to the piano track
* `guitar` - URL to the guitar track
* `vocals` - URL to the vocals track
* `other` - URL to other audio elements
#### stem-split
`stem_split` fields:
* `backing_vocals_url` - URL to backing vocals
* `bass_url` - URL to bass track
* `brass_url` - URL to brass instruments
* `drums_url` - URL to drums track
* `fx_url` - URL to sound effects
* `guitar_url` - URL to guitar track
* `keyboard_url` - URL to keyboard track
* `percussion_url` - URL to percussion track
* `strings_url` - URL to strings track
* `synth_url` - URL to synthesizer track
* `vocal_url` - URL to main vocals
* `woodwinds_url` - URL to woodwinds track
#### generate-music-cover
`generate_cover` is a JSON array containing cover image objects:
* `file_url` - URL to the generated cover image
* `file_type` - File type (e.g., "image")
## Callback Examples
### Music Generation (generate-music, extend-music, etc.)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"audio_id": "62e4542a-73be-44e1-b397-7716ee7505c6",
"audio_url": "https://storage.vidgo.ai/audio/8FDN1I7M7Q68DDG8/audio_62e4542a.mp3",
"image_url": "https://storage.vidgo.ai/audio/8FDN1I7M7Q68DDG8/cover_62e4542a.jpeg",
"title": "Peaceful Piano Meditation",
"tags": "Classical",
"duration": 240.0,
"prompt": ""
},
{
"audio_id": "8e755734-a840-4c13-beac-b9f1044979ca",
"audio_url": "https://storage.vidgo.ai/audio/8FDN1I7M7Q68DDG8/audio_8e755734.mp3",
"image_url": "https://storage.vidgo.ai/audio/8FDN1I7M7Q68DDG8/cover_8e755734.jpeg",
"title": "Peaceful Piano Meditation",
"tags": "Classical",
"duration": 130.0,
"prompt": ""
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### Timestamped Lyrics (get-timestamped-lyrics)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"timestampe_lyrics": "[00:00.00] First line of lyrics\n[00:05.23] Second line of lyrics"
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### Generated Lyrics (generate-lyrics)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"title": "Peaceful Piano Meditation",
"text": "Peaceful Piano Meditation lyrics content..."
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### Music Style Enhancement (boost-music-style)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"style": "Enhanced music style result"
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### WAV Conversion (convert-to-wav)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"wav_url": "https://storage.vidgo.ai/audio/8FDN1I7M7Q68DDG8/output.wav"
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### Vocal Separation (separate-vocals)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"separate_vocals": "{\"vocal_url\": \"https://storage.vidgo.ai/audio/vocals.mp3\", \"instrumental_url\": \"https://storage.vidgo.ai/audio/instrumental.mp3\"}"
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### Upload & Separate Vocals (upload-and-separate-vocals)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"vocal_removal": "{\"bass\": \"https://storage.vidgo.ai/audio/bass.mp3\", \"drums\": \"https://storage.vidgo.ai/audio/drums.mp3\", \"piano\": \"https://storage.vidgo.ai/audio/piano.mp3\", \"guitar\": \"https://storage.vidgo.ai/audio/guitar.mp3\", \"vocals\": \"https://storage.vidgo.ai/audio/vocals.mp3\", \"other\": \"https://storage.vidgo.ai/audio/other.mp3\"}"
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### Stem Split (stem-split)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"stem_split": "{\"backing_vocals_url\": \"\", \"bass_url\": \"\", \"brass_url\": \"\", \"drums_url\": \"\", \"fx_url\": \"\", \"guitar_url\": \"\", \"keyboard_url\": \"\", \"percussion_url\": \"\", \"strings_url\": \"\", \"synth_url\": \"\", \"vocal_url\": \"\", \"woodwinds_url\": \"\"}"
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### Music Cover Image (generate-music-cover)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"generate_cover": "[{\"file_url\": \"https://storage.vidgo.ai/audio/cover_1.png\", \"file_type\": \"image\"}, {\"file_url\": \"https://storage.vidgo.ai/audio/cover_2.png\", \"file_type\": \"image\"}]"
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### Generated Persona (generate-persona)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"persona_id": "persona_abc123"
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### Music Video (create-music-video)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "finished",
"files": [
{
"video_url": "https://storage.vidgo.ai/video/8FDN1I7M7Q68DDG8/music_video.mp4"
}
],
"created_time": "2025-11-25T08:50:13",
"error_message": null
}
}
```
### Failed Task
```json theme={null}
{
"code": 200,
"data": {
"task_id": "8FDN1I7M7Q68DDG8",
"status": "failed",
"files": [],
"created_time": "2025-11-25T08:50:13",
"error_message": "The prompt violates our content policy"
}
}
```
## Requirements
Your callback endpoint must meet the following requirements:
* **HTTPS only**: Must use HTTPS protocol (HTTP not supported)
* **Maximum URL length**: 2048 characters
* **Response timeout**: Must respond within 10 seconds
* **Success response**: Should return HTTP 200-299 status code
* **No internal IPs**: Cannot use private/internal IP addresses (e.g., 192.168.x.x, 10.x.x.x)
* **Public accessibility**: Must be publicly accessible from the internet
## Retry Policy
If your callback endpoint fails to respond or returns an error:
* **Retry attempts**: 3 automatic retries
* **Retry delays**: After 1 second, 2 seconds, and 4 seconds
* **Final failure**: After 3 failed attempts, no further retries are made
If all retry attempts fail, you can still retrieve the results by polling the [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Security Best Practices
**Verify requests**: Consider adding a signature verification mechanism to ensure requests are from Vidgo API
**Idempotency**: Design your webhook handler to be idempotent in case of duplicate deliveries
**Async processing**: Process the callback asynchronously and return 200 quickly to avoid timeouts
**Logging**: Log all webhook requests for debugging and monitoring
# Query Music Detail
Source: https://docs.vidgo.ai/api-manual/music-series/query-music-detail
api-manual/music-series/query-music-detail.json GET /api/generate/detail/music
Query detailed results of music generation tasks
## Usage Guide
* All POST submission requests in the Music Series can query their results through this endpoint. Different models will return different [response fields](#response-fields-files-data).
## Parameter Details
* `task_id` (required): The unique task identifier returned from the music generation submission endpoint
## Developer Notes
* Poll this endpoint to check task completion status
* The `files` array will be empty until the task status is `finished`
* When a task fails, check the `error_message` field for details
* Multiple audio files may be returned for a single task as variations are generated
## Response Fields (files data)
The `files` array content varies depending on which model created the task.
| Model | Field | Type | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ------------- | -------------------------------------------------------------------------------------- |
| `generate-music`, `extend-music`, `upload-and-cover-audio`, `upload-and-extend-audio`, `add-instrumental`, `add-vocals`, `replace-section` | `audio_id` | string | Unique identifier for the audio file |
| ↑ | `audio_url` | string | Direct download URL for the audio file |
| ↑ | `image_url` | string | Cover image URL |
| ↑ | `title` | string | Track title |
| ↑ | `tags` | string | Style tags |
| ↑ | `duration` | number | Audio duration in seconds |
| ↑ | `prompt` | string | Generation prompt used |
| `get-timestamped-lyrics` | `timestampe_lyrics` | string | Lyrics with timestamps |
| `generate-lyrics` | `title` | string | Lyrics title |
| ↑ | `text` | string | Complete lyrics content |
| `boost-music-style` | `style` | string | Enhanced music style |
| `convert-to-wav` | `wav_url` | string | URL to converted WAV file |
| `separate-vocals` | `separate_vocals` | string (JSON) | JSON string containing separated audio URLs. [See details](#separate-vocals) |
| `upload-and-separate-vocals` | `vocal_removal` | string (JSON) | JSON string containing separated stem URLs. [See details](#upload-and-separate-vocals) |
| `stem-split` | `stem_split` | string (JSON) | JSON string containing full stem separation URLs. [See details](#stem-split) |
| `generate-music-cover` | `generate_cover` | string (JSON) | JSON string containing generated cover images. [See details](#generate-music-cover) |
| `generate-persona` | `persona_id` | string | Generated persona identifier |
| `create-music-video` | `video_url` | string | Generated video URL |
### JSON Field Details
#### separate-vocals
`separate_vocals` fields:
* `vocal_url` - URL to the extracted vocal track
* `instrumental_url` - URL to the instrumental track
#### upload-and-separate-vocals
`vocal_removal` fields:
* `bass` - URL to the bass track
* `drums` - URL to the drums track
* `piano` - URL to the piano track
* `guitar` - URL to the guitar track
* `vocals` - URL to the vocals track
* `other` - URL to other audio elements
#### stem-split
`stem_split` fields:
* `backing_vocals_url` - URL to backing vocals
* `bass_url` - URL to bass track
* `brass_url` - URL to brass instruments
* `drums_url` - URL to drums track
* `fx_url` - URL to sound effects
* `guitar_url` - URL to guitar track
* `keyboard_url` - URL to keyboard track
* `percussion_url` - URL to percussion track
* `strings_url` - URL to strings track
* `synth_url` - URL to synthesizer track
* `vocal_url` - URL to main vocals
* `woodwinds_url` - URL to woodwinds track
#### generate-music-cover
`generate_cover` is a JSON array containing cover image objects:
* `file_url` - URL to the generated cover image
* `file_type` - File type (e.g., "image")
# Replace Section
Source: https://docs.vidgo.ai/api-manual/music-series/replace-section
api-manual/music-series/replace-section.json POST /api/generate/submit
Replace specific sections of generated music tracks
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint replaces a specific time range of an existing music track with new content
* Useful for editing verses, choruses, or any specific part of a generated track
* The replacement content is generated based on your prompt and style tags
## Parameter Details
* `task_id` (required): The original task ID from a completed music generation
* `audio_id` (required): The specific audio track identifier from the callback data
* `prompt` (required): Description of the replacement content (lyrics or musical description)
* `tags` (required): Style tags for the replacement section
* `title` (required): Title for the resulting track
* `infill_start_s` (required): Start time in seconds (minimum 0, up to 2 decimals)
* `infill_end_s` (required): End time in seconds (must be greater than start time)
## Developer Notes
* Ensure `infill_end_s` is always greater than `infill_start_s`
* The time range should be within the duration of the original track
* Use `full_lyrics` when you want to maintain lyrical consistency across the entire track
## Optional parameters
* `negative_tags` (string): Styles to exclude from the replacement section
* `full_lyrics` (string): Complete lyrics for the entire track after modification
* `callback_url` (string): Webhook URL for receiving completion notifications
# Upload and Cover Audio
Source: https://docs.vidgo.ai/api-manual/music-series/upload-and-cover-audio
api-manual/music-series/upload-and-cover-audio.json POST /api/generate/submit
Transform audio tracks into new styles while preserving the original melody
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint transforms an uploaded audio track into a new style while preserving the original melody
* Upload your audio file and specify the desired transformation style
* The original melody and structure are maintained while applying new musical characteristics
## Parameter Details
* **Audio Upload Requirement**:
* The uploaded audio must not exceed **8 minutes** in length
* **Note**: For the V4\_5ALL model, the uploaded audio must not exceed **1 minute** in length
* Provide a valid URL pointing to your audio file via `upload_url`
* In Custom Mode ( `custom_mode: true` ):
* `style` and `title` are **required**
* `prompt` is **required** if `instrumental` is `false`
* Character limits vary by model:
* **V4**: `prompt` 3000 characters, `style` 200 characters, `title` 80 characters
* **V4\_5 & V4\_5PLUS**: `prompt` 5000 characters, `style` 1000 characters, `title` 100 characters
* **V4\_5ALL**: `prompt` 5000 characters, `style` 1000 characters, `title` 80 characters
* **V5**: `prompt` 5000 characters, `style` 1000 characters, `title` 100 characters
* In Non-custom Mode ( `custom_mode: false` ):
* `prompt` is **required** to describe the desired transformation (max 500 characters)
* `style` and `title` should be left empty
## Developer Notes
* Ensure your audio URL is publicly accessible and the file is under 8 minutes (1 minute for V4\_5ALL)
* For best results, use high-quality source audio with clear melody lines
* The `audio_weight` parameter can help balance between preserving the original and applying the new style
## Optional parameters
* `negative_tags` (string): Music styles or characteristics to exclude from the cover.
* `vocal_gender` (string): Vocal gender preference. Use `m` for male, `f` for female. Note: This parameter increases the probability but cannot guarantee adherence.
* `style_weight` (number): Strength of adherence to the new style. Range 0-1, up to 2 decimals.
* `weirdness_constraint` (number): Controls creative deviation. Range 0-1, up to 2 decimals.
* `audio_weight` (number): Balance weight for preserving original audio features. Range 0-1, up to 2 decimals.
* `persona_id` (string): Persona ID to apply to the covered track. How to generate persona\_id, visit [generate-persona](/api-manual/music-series/generate-persona).
# Upload and Extend Audio
Source: https://docs.vidgo.ai/api-manual/music-series/upload-and-extend-audio
api-manual/music-series/upload-and-extend-audio.json POST /api/generate/submit
Extend audio tracks while preserving the original style
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
* This endpoint extends uploaded audio files while preserving the original style
* Upload an existing audio track and specify where to continue from
* The AI generates additional content that seamlessly blends with the original
* Uploaded audio files must not exceed 8 minutes in length (**Note**: For V4\_5ALL model, max 1 minute)
## Parameter Details
* When `default_param_flag: true` (Custom Parameters Mode):
* Full control over style, title, and other parameters
* If `instrumental: true`: only `style`, `title`, and `upload_url` are required
* If `instrumental: false`: `style`, `title`, `prompt` (used as exact lyrics), and `upload_url` are required
* Character limits vary by model:
* **V4**: `prompt` 3000 characters, `style` 200 characters, `title` 80 characters
* **V4\_5 & V4\_5PLUS**: `prompt` 5000 characters, `style` 1000 characters, `title` 100 characters
* **V4\_5ALL**: `prompt` 5000 characters, `style` 1000 characters, `title` 80 characters
* **V5**: `prompt` 5000 characters, `style` 1000 characters, `title` 100 characters
* When `default_param_flag: false`:
* Only `upload_url` is required. If `instrumental: false`, lyrics will be automatically generated
## Developer Notes
* Recommendation: Use `default_param_flag: false` for quick extensions that maintain the original style
* The `continue_at` parameter determines where the extension begins - set it to the point where you want new content to start
## Optional parameters
* `prompt` (string): Description or lyrics for the extended audio. Required when `default_param_flag` is `true` and `instrumental` is `false`. The prompt will be used strictly as lyrics. When `default_param_flag` is `false`, lyrics will be automatically generated based on the prompt.
* `style` (string): Music style specification. Required when `default_param_flag` is `true`.
* `title` (string): Track title for the extended audio. Character limits vary by model (V4: 80, V4\_5 & V4\_5PLUS & V5: 100, V4\_5ALL: 80).
* `negative_tags` (string): Music styles to exclude from generation.
* `vocal_gender` (string): Vocal gender preference. Use `m` for male, `f` for female. Note: This parameter can only increase the probability but cannot guarantee the specified gender.
* `style_weight` (number): Strength of adherence to style. Range 0-1, up to 2 decimals.
* `weirdness_constraint` (number): Controls creative deviation. Range 0-1, up to 2 decimals.
* `audio_weight` (number): Balance weight for audio features. Range 0-1, up to 2 decimals.
* `persona_id` (string): Persona ID to apply to the generated music. How to generate persona\_id, visit [generate-persona](/api-manual/music-series/generate-persona).
# Separate Vocals
Source: https://docs.vidgo.ai/api-manual/music-series/vocal-remover/separate-vocals
api-manual/music-series/vocal-remover/separate-vocals.json POST /api/generate/submit
Separate vocals and instruments from music tracks
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
**Vocal Separation Options:**
* [separate-vocals](/api-manual/music-series/vocal-remover/separate-vocals): Does not support uploading audio, 2-stem split, based on Suno
* [stem-split](/api-manual/music-series/vocal-remover/stem-split): Does not support uploading audio, 12-stem split, based on Suno
* [upload-and-separate-vocals](/api-manual/music-series/vocal-remover/upload-and-separate-vocals): Supports uploading audio, 7-stem split
* This endpoint separates vocals and instruments from music tracks
* Useful for remixing, karaoke tracks, or isolating specific instruments
## Parameter Details
* `task_id` (required): Task ID from a completed music generation (Generate Music or Extend Music)
* `audio_id` (required): Specific audio track identifier from the callback data
## Developer Notes
* Separation can only be performed once per audio track
* The callback includes download URLs for each separated track
* The task\_id from vocal separation is required for the Generate MIDI endpoint
# Stem Split
Source: https://docs.vidgo.ai/api-manual/music-series/vocal-remover/stem-split
api-manual/music-series/vocal-remover/stem-split.json POST /api/generate/submit
Split music tracks into multiple instrument stems
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
**Vocal Separation Options:**
* [separate-vocals](/api-manual/music-series/vocal-remover/separate-vocals): Does not support uploading audio, 2-stem split, based on Suno
* [stem-split](/api-manual/music-series/vocal-remover/stem-split): Does not support uploading audio, 12-stem split, based on Suno
* [upload-and-separate-vocals](/api-manual/music-series/vocal-remover/upload-and-separate-vocals): Supports uploading audio, 7-stem split
* This endpoint splits music tracks into multiple instrument stems
* Creates separate tracks for backing vocals, bass, brass, drums, fx, guitar, keyboard, percussion, strings, synth, vocals, woodwinds, and piano
* Useful for detailed remixing or isolating specific instruments
## Parameter Details
* `task_id` (required): Task ID from a completed music generation (Generate Music or Extend Music)
* `audio_id` (required): Specific audio track identifier from the callback data
## Developer Notes
* Stem split can only be performed once per audio track
* The callback includes download URLs for each separated stem
# Upload and Separate Vocals
Source: https://docs.vidgo.ai/api-manual/music-series/vocal-remover/upload-and-separate-vocals
api-manual/music-series/vocal-remover/upload-and-separate-vocals.json POST /api/generate/submit
Upload audio and separate it into multiple stems
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Music Detail](/api-manual/music-series/query-music-detail) endpoint.
## Usage Guide
**Vocal Separation Options:**
* [separate-vocals](/api-manual/music-series/vocal-remover/separate-vocals): Does not support uploading audio, 2-stem split, based on Suno
* [stem-split](/api-manual/music-series/vocal-remover/stem-split): Does not support uploading audio, 12-stem split, based on Suno
* [upload-and-separate-vocals](/api-manual/music-series/vocal-remover/upload-and-separate-vocals): Supports uploading audio, 7-stem split
* This endpoint uploads audio and separates it into multiple stems
* Creates separate tracks for bass, drums, piano, guitar, vocals, and other
* Useful for remixing or isolating specific instruments from uploaded audio
## Parameter Details
* `audio_url` (required): URL of the audio file to upload and separate
* `title` (optional): Title for the separation task
* `model_name` (optional): Separation model to use. Default: `base`
* `base`: Standard separation quality
* `enhanced`: Higher quality separation with better accuracy
* `instrumental`: Optimized for instrumental tracks
* `output_type` (optional): Type of output stems to generate. Default: `general`
* `general`: All available stems
* `bass`: Bass track only
* `drums`: Drums track only
* `other`: Other instruments
* `piano`: Piano track only
* `guitar`: Guitar track only
* `vocals`: Vocals track only
# Quick Start
Source: https://docs.vidgo.ai/api-manual/quickstart
Get started with Vidgo API in minutes
## Welcome to Vidgo API
Vidgo API provides powerful image and video generation APIs. This guide will help you make your first API call in just a few minutes.
## Step 1: Get Your API Key
1. Visit the [Vidgo API Console](https://vidgo.ai/apis/dashboard/api-key)
2. Sign in or create an account
3. Generate a new API key
4. **Important**: Copy and securely store your API key - it will only be displayed once
## Step 2: Generate Your First Image
All API requests require your API key in the `Authorization` header. Here's a complete example:
```python theme={null}
import requests
url = "https://api.vidgo.ai/api/generate/submit"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"model": "gpt-4o-image",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A serene mountain landscape at sunset with vibrant colors",
"size": "1:1",
"n": 1
}
}
response = requests.post(url, json=payload, headers=headers)
result = response.json()
task_id = result["data"]["task_id"]
print(f"Task ID: {task_id}")
```
```javascript theme={null}
const response = await fetch('https://api.vidgo.ai/api/generate/submit', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gpt-4o-image',
callback_url: 'https://your-domain.com/callback',
input: {
prompt: 'A serene mountain landscape at sunset with vibrant colors',
size: '1:1',
n: 1
}
})
});
const result = await response.json();
const taskId = result.data.task_id;
console.log(`Task ID: ${taskId}`);
```
```bash theme={null}
curl -X POST https://api.vidgo.ai/api/generate/submit \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-image",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A serene mountain landscape at sunset with vibrant colors",
"size": "1:1",
"n": 1
}
}'
```
## Step 3: Check Task Status
Vidgo API uses asynchronous processing. Poll the status endpoint to get your results:
```python theme={null}
import requests
import time
task_id = "task-unified-1757165031-uyujaw3d"
url = f"https://api.vidgo.ai/api/generate/status/{task_id}"
headers = {
"Authorization": "Bearer YOUR_API_KEY"
}
# Poll until complete
while True:
response = requests.get(url, headers=headers)
result = response.json()
task = result["data"]
status = task['status']
progress = task.get('progress', 0)
print(f"Status: {status}, Progress: {progress}%")
if status == 'finished':
print(f"Image URL: {task['files'][0]['file_url']}")
break
elif status == 'failed':
print(f"Error: {task['error_message']}")
break
time.sleep(2) # Wait 2 seconds before next check
```
```javascript theme={null}
const taskId = 'task-unified-1757165031-uyujaw3d';
async function checkStatus() {
while (true) {
const response = await fetch(
`https://api.vidgo.ai/api/generate/status/${taskId}`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const result = await response.json();
const task = result.data;
const { status, progress, files, error_message } = task;
console.log(`Status: ${status}, Progress: ${progress}%`);
if (status === 'finished') {
console.log('Image URL:', files[0].file_url);
break;
} else if (status === 'failed') {
console.log('Error:', error_message);
break;
}
await new Promise(resolve => setTimeout(resolve, 2000));
}
}
checkStatus();
```
```bash theme={null}
curl -X GET https://api.vidgo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Example Response:**
```json theme={null}
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "finished",
"progress": 100,
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/image-abc123.jpg",
"file_type": "image"
}
],
"created_time": "2025-11-12T10:30:00",
"error_message": null
}
}
```
**Content Validity**: Generated files are valid for 24 hours. Please download and save them promptly.
## Step 4: Try Video Generation
Generate videos using the same pattern. Just change the model and input parameters:
```python theme={null}
payload = {
"model": "sora-2",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A time-lapse of a bustling city street transitioning from day to night",
"duration": 10,
"aspect_ratio": "16:9"
}
}
```
## Step 5: Try Music Generation
Generate music with customizable styles and vocals:
```python theme={null}
payload = {
"model": "generate-music",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "A calm and relaxing piano track with soft melodies",
"style": "Classical",
"title": "Peaceful Piano Meditation",
"custom_mode": True,
"instrumental": True,
"mv": "V5"
}
}
```
## Support
Need help? We're here to assist:
* **Email**: [support@vidgo.ai](mailto:support@vidgo.ai)
* **Console**: [vidgo.ai](https://vidgo.ai/apis)
# Get Task Status
Source: https://docs.vidgo.ai/api-manual/task-management/status
GET /api/generate/status/{task_id}
Query task execution status and retrieve generation results
# Get Task Status
Query the execution status of image and video generation tasks and retrieve results when complete.
## Endpoint
```http theme={null}
GET https://api.vidgo.ai/api/generate/status/{task_id}
```
## Authentication
All requests require Bearer token authentication:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
Generate your API key from the console
## Parameters
### Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------- |
| `task_id` | string | Yes | Unique task identifier returned from the submit endpoint |
## Response
### Success Response (200)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/image-abc123.jpg",
"file_type": "image"
}
],
"created_time": "2025-11-12T10:30:00",
"progress": 100,
"error_message": null
}
}
```
### Response Fields
| Field | Type | Description |
| ------------------------ | ------- | ----------------------------------------------------------- |
| `code` | integer | HTTP status code (200 for success) |
| `data.task_id` | string | Unique task identifier |
| `data.status` | string | Task status: `not_started`, `running`, `finished`, `failed` |
| `data.files` | array | Generated media files (when status is `finished`) |
| `data.files[].file_url` | string | Direct URL to generated file |
| `data.files[].file_type` | string | Type of media file: `image` or `video` |
| `data.created_time` | string | ISO 8601 timestamp of task creation |
| `data.progress` | integer | Completion percentage (0-100) |
| `data.error_message` | string | Error description (when status is `failed`) |
### Status Values
| Status | Description |
| ------------- | --------------------------------------------------------- |
| `not_started` | Task is queued, waiting to be processed |
| `running` | Task is currently being generated |
| `finished` | Task completed successfully, results available in `files` |
| `failed` | Task failed, error details in `error_message` |
## Response Examples by Status
### Not Started
```json theme={null}
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"files": [],
"created_time": "2025-11-12T10:30:00",
"progress": 0,
"error_message": null
}
}
```
### Running (Image)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "running",
"files": [],
"created_time": "2025-11-12T10:30:00",
"progress": 45,
"error_message": null
}
}
```
### Finished (Image)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/image-abc123.jpg",
"file_type": "image"
}
],
"created_time": "2025-11-12T10:30:00",
"progress": 100,
"error_message": null
}
}
```
### Finished (Video)
```json theme={null}
{
"code": 200,
"data": {
"task_id": "task-unified-1757165211-xyz789",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video-xyz789.mp4",
"file_type": "video"
}
],
"created_time": "2025-11-12T10:30:00",
"progress": 100,
"error_message": null
}
}
```
### Failed
```json theme={null}
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "failed",
"files": [],
"created_time": "2025-11-12T10:30:00",
"progress": 0,
"error_message": "The prompt violates our content policy"
}
}
```
## Code Examples
### cURL
```bash theme={null}
curl -X GET https://api.vidgo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Python
```python theme={null}
import requests
API_KEY = "your-api-key-here"
task_id = "task-unified-1757165031-uyujaw3d"
response = requests.get(
f"https://api.vidgo.ai/api/generate/status/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"}
)
result = response.json()
data = result["data"]
print(f"Status: {data['status']}")
print(f"Progress: {data['progress']}%")
if data["status"] == "finished":
for file in data["files"]:
print(f"Generated file: {file['file_url']}")
elif data["status"] == "failed":
print(f"Error: {data['error_message']}")
```
### JavaScript / Node.js
```javascript theme={null}
const API_KEY = 'your-api-key-here';
const taskId = 'task-unified-1757165031-uyujaw3d';
const response = await fetch(
`https://api.vidgo.ai/api/generate/status/${taskId}`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
const result = await response.json();
const data = result.data;
console.log(`Status: ${data.status}`);
console.log(`Progress: ${data.progress}%`);
if (data.status === 'finished') {
data.files.forEach(file => {
console.log(`Generated file: ${file.file_url}`);
});
} else if (data.status === 'failed') {
console.log(`Error: ${data.error_message}`);
}
```
### Go
```go theme={null}
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
)
const (
APIKey = "your-api-key-here"
BaseURL = "https://api.vidgo.ai"
)
type APIResponse struct {
Code int `json:"code"`
Data TaskData `json:"data"`
}
type TaskData struct {
TaskID string `json:"task_id"`
Status string `json:"status"`
Files []MediaFile `json:"files"`
CreatedTime string `json:"created_time"`
Progress int `json:"progress"`
ErrorMessage *string `json:"error_message"`
}
type MediaFile struct {
FileURL string `json:"file_url"`
FileType string `json:"file_type"`
}
func main() {
taskID := "task-unified-1757165031-uyujaw3d"
req, _ := http.NewRequest(
"GET",
fmt.Sprintf("%s/api/generate/status/%s", BaseURL, taskID),
nil,
)
req.Header.Set("Authorization", "Bearer "+APIKey)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var apiResp APIResponse
json.Unmarshal(body, &apiResp)
data := apiResp.Data
fmt.Printf("Status: %s\n", data.Status)
fmt.Printf("Progress: %d%%\n", data.Progress)
if data.Status == "finished" {
for _, file := range data.Files {
fmt.Printf("Generated file: %s\n", file.FileURL)
}
} else if data.Status == "failed" {
fmt.Printf("Error: %s\n", *data.ErrorMessage)
}
}
```
### Java
```java theme={null}
import java.net.http.*;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
public class VidgoAPI {
private static final String API_KEY = "your-api-key-here";
private static final String BASE_URL = "https://api.vidgo.ai";
public static void main(String[] args) throws Exception {
String taskId = "task-unified-1757165031-uyujaw3d";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(BASE_URL + "/api/generate/status/" + taskId))
.header("Authorization", "Bearer " + API_KEY)
.GET()
.build();
HttpResponse response = client.send(
request,
HttpResponse.BodyHandlers.ofString()
);
ObjectMapper mapper = new ObjectMapper();
JsonNode root = mapper.readTree(response.body());
JsonNode data = root.get("data");
String status = data.get("status").asText();
int progress = data.get("progress").asInt();
System.out.println("Status: " + status);
System.out.println("Progress: " + progress + "%");
if ("finished".equals(status)) {
JsonNode files = data.get("files");
files.forEach(file -> {
System.out.println("Generated file: " + file.get("file_url").asText());
});
} else if ("failed".equals(status)) {
System.out.println("Error: " + data.get("error_message").asText());
}
}
}
```
### PHP
```php theme={null}
**Poll Interval**: Check status every 2-5 seconds. Avoid polling more frequently to prevent rate limiting.
**Timeout**: Implement timeouts to avoid infinite loops. Typical generation times:
* Images: 15-60 seconds
* Videos: 90-300 seconds
**Exponential Backoff**: On rate limit (429) or server errors (5xx), implement exponential backoff (wait 1s, 2s, 4s, 8s...).
### Complete Polling Example
```python theme={null}
import requests
import time
API_KEY = "your-api-key-here"
BASE_URL = "https://api.vidgo.ai"
def wait_for_completion(task_id, timeout=600, poll_interval=2):
"""
Wait for task completion with timeout
Args:
task_id: Task identifier
timeout: Maximum wait time in seconds
poll_interval: Seconds between checks
Returns:
Task data when complete
Raises:
TimeoutError: If timeout exceeded
RuntimeError: If task failed
"""
start_time = time.time()
headers = {"Authorization": f"Bearer {API_KEY}"}
while True:
# Check timeout
if time.time() - start_time > timeout:
raise TimeoutError(f"Task did not complete within {timeout}s")
# Get status
response = requests.get(
f"{BASE_URL}/api/generate/status/{task_id}",
headers=headers
)
if response.status_code == 429:
# Rate limited - wait longer
time.sleep(poll_interval * 2)
continue
response.raise_for_status()
result = response.json()
data = result["data"]
# Log progress
elapsed = int(time.time() - start_time)
print(f"[{elapsed}s] Status: {data['status']}, Progress: {data['progress']}%")
# Check completion
if data["status"] == "finished":
print(f"闁?Task completed successfully")
return data
elif data["status"] == "failed":
raise RuntimeError(f"Task failed: {data['error_message']}")
time.sleep(poll_interval)
# Usage
try:
task_id = "task-unified-1757165031-uyujaw3d"
result = wait_for_completion(task_id)
for file in result["files"]:
print(f"Download: {file['file_url']}")
except TimeoutError as e:
print(f"Timeout: {e}")
except RuntimeError as e:
print(f"Error: {e}")
```
## Error Responses
### HTTP Error Codes
| Code | Description | Action |
| ---- | ----------------- | ------------------------------------------- |
| 401 | Unauthorized | Check your API key |
| 403 | Forbidden | Task belongs to another user |
| 404 | Not Found | Task ID does not exist |
| 429 | Too Many Requests | Reduce polling frequency, implement backoff |
| 500 | Server Error | Retry with exponential backoff |
| 502 | Bad Gateway | Service temporarily unavailable, retry |
### Error Response Format
```json theme={null}
{
"detail": "Task not found"
}
```
## Important Notes
**Content Validity**: Generated images and videos are accessible for **24 hours** after creation. Download and save your content promptly.
**Credits**: Credits are only deducted when the task status becomes `finished`. Failed tasks do not consume credits.
**Webhooks**: Instead of polling, you can provide a `callback_url` when submitting tasks to receive automatic notifications. See the [Quick Start guide](/guides/getting-started/quickstart#webhook-callbacks).
## Next Steps
Learn how to submit generation tasks
Generate images with GPT-4o
Create videos with Sora 2
Complete integration guide
# Webhook Callbacks
Source: https://docs.vidgo.ai/api-manual/task-management/webhooks
Receive automatic notifications when tasks complete
# Webhook Callbacks
Instead of polling the status endpoint, you can provide a callback URL when submitting tasks to receive automatic notifications when generation completes.
## How It Works
1. **Submit with callback URL**: Include a `callback_url` in your task submission
2. **Receive notification**: When the task completes (success or failure), Vidgo API sends a POST request to your URL
3. **Process result**: Your server receives the complete task data including generated files
## Callback Request
When a task completes, Vidgo API will send a POST request to your callback URL with the same structure as the [status endpoint response](/api-manual/task-management/status):
```json theme={null}
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/image-abc123.jpg",
"file_type": "image"
}
],
"created_time": "2025-11-12T10:30:00",
"progress": 100,
"error_message": null
}
}
```
### Failed Task Callback
```json theme={null}
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "failed",
"files": [],
"created_time": "2025-11-12T10:30:00",
"progress": 0,
"error_message": "The prompt violates our content policy"
}
}
```
## Requirements
Your callback endpoint must meet the following requirements:
* **HTTPS only**: Must use HTTPS protocol (HTTP not supported)
* **Maximum URL length**: 2048 characters
* **Response timeout**: Must respond within 10 seconds
* **Success response**: Should return HTTP 200-299 status code
* **No internal IPs**: Cannot use private/internal IP addresses (e.g., 192.168.x.x, 10.x.x.x)
* **Public accessibility**: Must be publicly accessible from the internet
## Retry Policy
If your callback endpoint fails to respond or returns an error:
* **Retry attempts**: 3 automatic retries
* **Retry delays**: After 1 second, 2 seconds, and 4 seconds
* **Final failure**: After 3 failed attempts, no further retries are made
If all retry attempts fail, you can still retrieve the results by polling the [status endpoint](/api-manual/task-management/status).
## Example Implementation
### Python (Flask)
```python theme={null}
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhook/generation-complete', methods=['POST'])
def handle_generation_complete():
# Parse the callback payload
data = request.json
task_data = data.get('data', {})
task_id = task_data.get('task_id')
status = task_data.get('status')
if status == 'finished':
# Task completed successfully
files = task_data.get('files', [])
for file in files:
print(f"Generated file: {file['file_url']}")
# Download and process the file
# save_file(file['file_url'])
elif status == 'failed':
# Task failed
error = task_data.get('error_message')
print(f"Task {task_id} failed: {error}")
# Handle the failure
# Return 200 to acknowledge receipt
return jsonify({"received": True}), 200
if __name__ == '__main__':
app.run(host='0.0.0.0', port=443, ssl_context='adhoc')
```
### Node.js (Express)
```javascript theme={null}
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhook/generation-complete', (req, res) => {
const { data } = req.body;
const { task_id, status, files, error_message } = data;
if (status === 'finished') {
// Task completed successfully
console.log(`Task ${task_id} completed`);
files.forEach(file => {
console.log(`Generated file: ${file.file_url}`);
// Download and process the file
});
} else if (status === 'failed') {
// Task failed
console.log(`Task ${task_id} failed: ${error_message}`);
// Handle the failure
}
// Return 200 to acknowledge receipt
res.status(200).json({ received: true });
});
const https = require('https');
const fs = require('fs');
const options = {
key: fs.readFileSync('private-key.pem'),
cert: fs.readFileSync('certificate.pem')
};
https.createServer(options, app).listen(443, () => {
console.log('Webhook server listening on port 443');
});
```
### Go
```go theme={null}
package main
import (
"encoding/json"
"fmt"
"net/http"
)
type CallbackPayload struct {
Code int `json:"code"`
Data TaskData `json:"data"`
}
type TaskData struct {
TaskID string `json:"task_id"`
Status string `json:"status"`
Files []MediaFile `json:"files"`
CreatedTime string `json:"created_time"`
Progress int `json:"progress"`
ErrorMessage *string `json:"error_message"`
}
type MediaFile struct {
FileURL string `json:"file_url"`
FileType string `json:"file_type"`
}
func handleWebhook(w http.ResponseWriter, r *http.Request) {
var payload CallbackPayload
if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
taskData := payload.Data
if taskData.Status == "finished" {
// Task completed successfully
fmt.Printf("Task %s completed\n", taskData.TaskID)
for _, file := range taskData.Files {
fmt.Printf("Generated file: %s\n", file.FileURL)
// Download and process the file
}
} else if taskData.Status == "failed" {
// Task failed
fmt.Printf("Task %s failed: %s\n", taskData.TaskID, *taskData.ErrorMessage)
// Handle the failure
}
// Return 200 to acknowledge receipt
w.WriteHeader(http.StatusOK)
json.NewEncoder(w).Encode(map[string]bool{"received": true})
}
func main() {
http.HandleFunc("/webhook/generation-complete", handleWebhook)
// Use HTTPS
err := http.ListenAndServeTLS(":443", "cert.pem", "key.pem", nil)
if err != nil {
panic(err)
}
}
```
## Security Best Practices
**Verify requests**: Consider adding a signature verification mechanism to ensure requests are from Vidgo API
**Idempotency**: Design your webhook handler to be idempotent in case of duplicate deliveries
**Async processing**: Process the callback asynchronously and return 200 quickly to avoid timeouts
**Logging**: Log all webhook requests for debugging and monitoring
## Testing
### Using ngrok for Local Testing
During development, you can use [ngrok](https://ngrok.com) to expose your local server:
```bash theme={null}
# Start your local webhook server on port 3000
node webhook-server.js
# In another terminal, start ngrok
ngrok http 3000
# Use the HTTPS URL provided by ngrok as your callback_url
# Example: https://abc123.ngrok.io/webhook/generation-complete
```
## Webhook vs Polling
| Method | Best For | Pros | Cons |
| ------------ | -------------------------------- | -------------------------------------------- | ----------------------------------------- |
| **Webhooks** | Production systems | Real-time notifications, no polling overhead | Requires public endpoint, harder to debug |
| **Polling** | Development, simple integrations | Easy to implement, no server required | Higher latency, consumes more resources |
For production systems handling high volumes, webhooks are recommended to reduce API calls and get instant notifications.
## Next Steps
Learn about polling task status
Generate images with GPT-4o
Create videos with Sora 2
Back to Quick Start guide
# Grok Imagine Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/grok-imagine
api-manual/video-series/grok-imagine.json POST /api/generate/submit
High-quality video generation with Grok Imagine
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Grok Imagine Video Generation
Generate high-quality videos using Grok Imagine. Create engaging content with text-to-video and image-to-video capabilities.
## Available Model
* **grok-imagine** - Video generation (text-to-video and image-to-video)
## Key Features
* **Flexible Modes**: Text-to-video and image-to-video
* **Generation Styles**: Choose from "fun", "normal", or "spicy" modes
* **Aspect Ratios**: 1:1 (square), 2:3 (portrait), and 3:2 (landscape)
* **Video Duration**: `6` or `10` seconds
# Grok Imagine Video 1.5
Source: https://docs.vidgo.ai/api-manual/video-series/grok-imagine-video-1-5
api-manual/video-series/grok-imagine-video-1-5.json POST /api/generate/submit
Text, image, and reference-to-video generation with Grok Imagine Video 1.5
# Grok Imagine Video 1.5
Create 1–15 second videos from text, a single first-frame image, or up to seven reference images.
After submission, use the returned `task_id` with the video status endpoint, or provide `callback_url` to receive the completed result.
## Generation modes
* **Text to video:** omit both image fields. Supports `480p`, `720p`, and `1080p`.
* **Image to video:** provide exactly one URL in `image_urls`. Supports `480p`, `720p`, and `1080p`.
* **Reference to video:** provide 1–7 URLs in `reference_image_urls` and refer to them as ``, ``, and so on. Supports `480p` and `720p`.
`image_urls` and `reference_image_urls` cannot be used together. `aspect_ratio` is available for text and reference modes, but not first-frame image-to-video.
## Parameters
* `prompt` (required): up to 4,096 characters.
* `resolution`: `480p`, `720p`, or `1080p`. Default: `720p`.
* `duration`: integer from `1` to `15`. Default: `6` for text/image mode and `8` for reference mode.
* `aspect_ratio`: `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, or `9:16`. Default: `16:9` where supported.
* `callback_url`: optional HTTPS completion webhook.
## Billing
Video output is billed per second by resolution: 14.5 credits at 480p, 25 credits at 720p, and 45 credits at 1080p. Each submitted input or reference image adds 2 credits.
Use public HTTPS image URLs or upload images through the playground before submitting.
# Hailuo 02 Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/hailuo-02
api-manual/video-series/hailuo-02.json POST /api/generate/submit
Advanced video generation with Hailuo 02
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Hailuo 02 Video Generation
Generate high-quality videos using Hailuo 02 models. Create professional content with text-to-video and image-to-video capabilities.
## Available Models
* **hailuo-02** - Standard video generation (768P/512P, up to 10 seconds)
* **hailuo-02-pro** - Professional video generation (1080P, 6 seconds)
## Key Features
* **Flexible Modes**: Text-to-video and image-to-video
* **Multiple Resolutions**: 512P, 768P (Standard) and 1080P (Pro)
* **Duration Options**: 6 or 10 seconds (Standard only)
* **Prompt Optimizer**: Optional AI-powered prompt enhancement
* **End Frame Control**: Specify ending frame for image-to-video (optional)
# Hailuo 2.3
Source: https://docs.vidgo.ai/api-manual/video-series/hailuo-2-3
api-manual/video-series/hailuo-2-3.json POST /api/generate/submit
Text-to-video and optional first-frame guided generation
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Hailuo 2.3
`hailuo-2.3` supports prompt-only generation and optional first-frame guided generation.
## Available Model
* **hailuo-2.3** - Text-to-video with optional `start_image_url`
## Required Parameters
* **prompt**: Text prompt for video generation
## Optional Parameters
* **duration**: `6` or `10`. Default is `6`
* **resolution**: `768p` or `1080p`. Default is `768p`
* **start\_image\_url**: Optional first-frame image
* **prompt\_optimizer**: Optional boolean switch
## Notes
* `end_image_url` is not supported
* `1080p` only supports `duration=6`
# Happy Horse
Source: https://docs.vidgo.ai/api-manual/video-series/happy-horse
api-manual/video-series/happy-horse.json POST /api/generate/submit
Alibaba Happy Horse text-to-video, image-to-video, reference-to-video, and video-edit workflows
1. After submission, a `task_id` is returned immediately. If you provide a `callback_url`, Vidgo sends a POST request to that URL when the task reaches `finished` or `failed`.
2. You can always fetch the latest task result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Happy Horse
`happy-horse` supports text-to-video, image-to-video, reference-to-video, and video-edit through one public model ID.
## Available Model
* **happy-horse** - Alibaba Happy Horse 1.0 video generation and editing
## Workflows
### Text to Video
Send a `prompt` without image or video input fields. Use `aspect_ratio`, `resolution`, and `duration` to control the output.
### Image to Video
Send a single-item `image_urls` array. The image is used as the first frame. `prompt` is optional in this workflow.
### Reference to Video
Send `reference_image_urls` with 1-9 images and a required `prompt`. Reference the images in prompt text as `character1`, `character2`, and so on, matching the order of `reference_image_urls`.
Do not combine `reference_image_urls` with `image_urls`.
### Video Edit
Send `video_url` with a required edit `prompt`. Optional `reference_image_urls` can guide the edit; refer to them as `@Image1`, `@Image2`, and so on. `audio_setting` controls whether Happy Horse decides audio handling automatically or preserves the original audio.
The source video must be 3-60 seconds. Video-edit billing uses the probed source video duration according to the current workflow pricing configuration.
## Pricing
Happy Horse billing depends on the selected workflow, output resolution, and billable video duration. Check the Vidgo pricing page or dashboard for the current rate before submitting production traffic.
Text-to-video, image-to-video, and reference-to-video use the requested `duration`. Video-edit uses the probed source video duration, capped at the maximum billable duration for this workflow.
## Required Parameters
* **model**: `happy-horse`
* **input.prompt**: Required for text-to-video, reference-to-video, and video-edit. Optional for image-to-video.
* **input.video\_url**: Required for video-edit.
* **input.reference\_image\_urls**: Required for reference-to-video.
## Optional Parameters
* **image\_urls**: Single-item first-frame image URL array for image-to-video
* **reference\_image\_urls**: 1-9 images for reference-to-video, or up to 5 optional images for video-edit
* **aspect\_ratio**: Text-to-video and reference-to-video only. `16:9`, `9:16`, `1:1`, `4:3`, or `3:4`. Default is `16:9`
* **resolution**: `720p` or `1080p`. Default is `1080p`
* **duration**: Integer seconds from `3` to `15` for text-to-video, image-to-video, and reference-to-video. Ignored for video-edit
* **audio\_setting**: Video-edit only. `auto` or `origin`. Default is `auto`
* **seed**: Optional integer from `0` to `2147483647`
* **enable\_safety\_checker**: Optional boolean
## Notes
* `image_urls` must resolve to exactly one image and is only for image-to-video.
* `reference_image_urls` selects reference-to-video unless `video_url` is present, in which case it is treated as optional video-edit reference imagery.
* For text-to-video and reference-to-video, omit `video_url` and use `aspect_ratio`.
* For video-edit, omit `duration`; the backend probes the source video duration for validation and duration-based billing.
# Kling 1.6 Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/kling-1-6
api-manual/video-series/kling-1-6.json POST /api/generate/submit
Kling 1.6 Standard and Pro video generation through the Vidgo API
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, Vidgo sends a POST request when the task becomes `finished` or `failed`.
2. You can always retrieve the result through the unified Query Task Status endpoint.
## Available Models
* **kling-1.6/standard** - Cost-effective Kling 1.6 video generation at 9 credits per second.
* **kling-1.6/pro** - Higher-quality Kling 1.6 video generation at 15 credits per second.
## Input Routing
Vidgo does not require a public `mode`, `type`, or `task_type` field for Kling 1.6.
All Kling 1.6 requests require `prompt` and `duration`.
* Provide no image fields to generate text-to-video.
* Provide `start_image_url` to generate image-to-video.
* Provide `start_image_url` and `end_image_url` with `kling-1.6/pro` to control both the first and last frame.
* Provide `image_urls` with 1 to 4 reference images to generate Elements.
`image_urls` cannot be used together with `start_image_url`, `end_image_url`, or `cfg_scale`.
## Parameter Compatibility
| Model and workflow | How Vidgo detects it | Supported parameters |
| ----------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Text to Video (`standard` or `pro`) | No image fields | `prompt`, `duration`, `aspect_ratio`, `negative_prompt`, `cfg_scale` |
| Standard Image to Video | `kling-1.6/standard` with `start_image_url` | `prompt`, `duration`, `start_image_url`, `negative_prompt`, `cfg_scale` |
| Pro Image to Video | `kling-1.6/pro` with `start_image_url` and optional `end_image_url` | `prompt`, `duration`, `aspect_ratio`, `start_image_url`, `end_image_url`, `negative_prompt`, `cfg_scale` |
| Elements (`standard` or `pro`) | `image_urls` | `prompt`, `duration`, `aspect_ratio`, `negative_prompt`, `image_urls` |
Notes:
* `end_image_url` requires `start_image_url` and is only supported by `kling-1.6/pro`.
* `kling-1.6/standard` image-to-video does not support `aspect_ratio`.
* Elements supports 1 to 4 `image_urls` and does not support `cfg_scale`.
* `prompt` and `negative_prompt` support up to 2500 characters.
* `cfg_scale` must be between 0 and 1 when provided.
## Response and Status
The submit endpoint returns a Vidgo `task_id`. Use it with the unified Query Task Status endpoint to retrieve the final video URL.
Initial submit responses include `status`, which is usually `running` after the upstream video task has been created. If submission fails during upstream task creation, the status may be `failed` and the task can be inspected through the status endpoint.
## Pricing
* **kling-1.6/standard**: 9 credits per second.
* **kling-1.6/pro**: 15 credits per second.
# Kling 2.1
Source: https://docs.vidgo.ai/api-manual/video-series/kling-2-1
api-manual/video-series/kling-2-1.json POST /api/generate/submit
Standard and Pro image-to-video generation
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Kling 2.1
Kling 2.1 provides two public models under the same request format: `kling-2.1/standard` and `kling-2.1/pro`.
## Available Models
* **kling-2.1/standard** - Start-frame guided image-to-video
* **kling-2.1/pro** - Start-frame guided image-to-video with optional end frame
## Required Parameters
* **prompt**: Text prompt for generation
* **start\_image\_url**: Required first frame image
## Optional Parameters
* **duration**: `5` or `10`. Default is `5`
* **end\_image\_url**: Optional, only supported by `kling-2.1/pro`
* **negative\_prompt**: Optional negative prompt
## Notes
* `kling-2.1/standard` does not support `end_image_url`
* `kling-2.1/pro` supports both start image and optional end image
# Kling 2.5 Turbo Pro
Source: https://docs.vidgo.ai/api-manual/video-series/kling-2-5-turbo-pro
api-manual/video-series/kling-2-5-turbo-pro.json POST /api/generate/submit
Prompt-based video generation with optional start and end frame guidance
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Kling 2.5 Turbo Pro
`kling-2.5-turbo-pro` supports prompt-only generation and optional start/end frame guidance in the same request format.
## Available Model
* **kling-2.5-turbo-pro** - Text-to-video with optional frame guidance
## Required Parameters
* **prompt**: Text prompt for generation
## Optional Parameters
* **duration**: `5` or `10`. Default is `5`
* **start\_image\_url**: Optional first frame image
* **end\_image\_url**: Optional last frame image
* **aspect\_ratio**: Optional string value
* **negative\_prompt**: Optional negative prompt
## Notes
* You can submit prompt-only requests
* You can also provide `start_image_url`, `end_image_url`, or both
# Kling 2.6 Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/kling-2-6
api-manual/video-series/kling-2-6.json POST /api/generate/submit
Advanced video generation with native audio support
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Kling 2.6 Video Generation
Generate high-quality videos with native audio support using Kling 2.6. Create cinematic content with synchronized dialogue, singing, sound effects, and ambient audio.
## Available Model
* **kling-2.6** - Video generation with native audio (text-to-video and image-to-video)
## Key Features
* **Native Audio**: Synchronized speech, singing, sound effects, and ambient sounds
* **Flexible Duration**: 5 or 10 seconds
* **Aspect Ratios**: 1:1 (square), 16:9 (landscape), and 9:16 (portrait)
* **Modes**: Text-to-video and image-to-video
## Notes
* `end_image_url` is supported as an optional last-frame image for image-to-video requests.
* When `end_image_url` is provided, `input.sound` must be `false`.
# Kling 2.6 Motion Control
Source: https://docs.vidgo.ai/api-manual/video-series/kling-2.6-motion-control
api-manual/video-series/kling-2.6-motion-control.json POST /api/generate/submit
Advanced motion transfer with character animation
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Kling 2.6 Motion Control
Transfer motion from reference videos to character images with precise motion control. Create dynamic character animations by combining static images with motion reference videos while controlling scene details through text prompts.
## Available Model
* **kling-2.6-motion-control** - Motion transfer from video to character image
## Key Features
* **Motion Transfer**: Transfer real human motion, gestures, and expressions from reference videos to character images
* **Character Animation**: Animate static characters with dynamic motion patterns
* **Character Orientation Control**: Choose between matching image orientation (max 10s output) or video orientation (max 30s output)
* **Scene Control**: Control scene details and environment through optional text prompts
* **Flexible Resolution**: Choose between 720p (standard) or 1080p (high quality) output
## Required Parameters
* **image\_urls**: Single character image showing the subject's head, shoulders, and torso
* **video\_urls**: Single reference video (3-30 seconds) for motion transfer
* **character\_orientation**:
* `"image"` - Matches the person's orientation in the photograph (maximum 10-second output)
* `"video"` - Maintains consistency with character orientation from the reference video (maximum 30-second output)
* **mode**: Output resolution (`"720p"` or `"1080p"`)
## Optional Parameters
* **prompt**: Text description of the desired output scene (max 2,500 characters)
# Kling 3.0 Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/kling-3-0
api-manual/video-series/kling-3-0.json POST /api/generate/submit
Next-generation video generation with standard and pro resolution
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
## Available Models
* **kling-3.0/standard** - HD resolution (\~720p/1K)
* **kling-3.0/pro** - Full HD resolution (1080p/2K), sharper and more detailed output
## Key Features
* **Native Audio**: Controlled by `input.sound`. Set `true` to enable sound effects and `false` to disable them. When `multi_shots` is `true`, `sound` must be `true`
* **Flexible Duration**: 3 to 15 seconds
* **Aspect Ratios**: 1:1 (square), 16:9 (landscape), and 9:16 (portrait)
* **Modes**: Text-to-video and image-to-video (start and end frames)
* **Multi-Shot**: Multi-shot storytelling with per-shot prompts and durations
* **Element References**: Define reusable elements (via images or video) and reference them in prompts using `@element_name` syntax. `image_urls` is required when using element references
# Kling 3.0 Motion Control
Source: https://docs.vidgo.ai/api-manual/video-series/kling-3-0-motion-control
api-manual/video-series/kling-3-0-motion-control.json POST /api/generate/submit
Reference image and reference video motion transfer
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Kling 3.0 Motion Control
`kling-3.0-motion-control` combines one reference image and one reference video to transfer motion to the target character.
## Available Model
* **kling-3.0-motion-control** - Motion transfer from reference video to reference image
## Required Parameters
* **image\_urls**: Exactly `1` reference image
* **video\_urls**: Exactly `1` reference video
* **character\_orientation**: `image` or `video`
## Optional Parameters
* **prompt**: Optional scene prompt
* **resolution**: `720p` or `1080p`. Default is `720p`
## Notes
* Images support `.jpg`, `.jpeg`, `.png`, up to `10MB`
* Videos support `.mp4`, `.mov`, up to `100MB`
* Reference video must be at least `3` seconds
* When `character_orientation=image`, the reference video must not exceed `10` seconds
* When `character_orientation=video`, the reference video must not exceed `30` seconds
# Runway Gen-4.5
Source: https://docs.vidgo.ai/api-manual/video-series/runway-gen-4-5
api-manual/video-series/runway-gen-4-5.json POST /api/generate/submit
Video generation with optional reference image, 5s and 10s durations
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Runway Gen-4.5
`runway-gen-4.5` is exposed through the unified submit endpoint with text-to-video and optional single-image guidance.
## Available Model
* **runway-gen-4.5** - Text-to-video generation
## Required Parameters
* **prompt**: Text prompt for generation
## Optional Parameters
* **duration**: `5` or `10`. Default is `5`
* **aspect\_ratio**: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`, or `21:9`. Default is `16:9`
* **image\_urls**: Optional image URL list. At most `1` image
* **seed**: Optional integer seed
## Notes
* `image_urls` is optional. If provided, only one image URL is allowed
# Seedance 1.5 Pro Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/seedance-1-5-pro
api-manual/video-series/seedance-1-5-pro.json POST /api/generate/submit
High-quality text-to-video and image-to-video generation with Seedance 1.5 Pro
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Seedance 1.5 Pro Video Generation
Generate high-quality videos from text prompts or reference images using Seedance 1.5 Pro by ByteDance. Control aspect ratio, resolution, duration, and optional audio generation.
## Available Model
* **seedance-1.5-pro** - Text-to-video and image-to-video generation with enhanced fidelity
## Key Features
* **Flexible Modes**: Supports text-to-video and image-to-video generation
* **Aspect Ratio Control**: Flexible output aspect ratios
* **Resolution Control**: Choose the target output resolution
* **Duration Control**: Set duration in seconds
* **Fixed Lens**: Lock the camera lens for steady framing
* **Audio Generation**: Optionally generate an audio track
# Seedance 1.0 Pro Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/seedance-1.0-pro
api-manual/video-series/seedance-1.0-pro.json POST /api/generate/submit
High-quality text-to-video and image-to-video generation with Seedance 1.0 Pro
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Seedance 1.0 Pro Video Generation
Generate high-quality videos from text prompts or reference images using Seedance 1.0 Pro by ByteDance. Create smooth, professional animations with flexible duration and resolution options.
## Available Model
* **seedance-1.0-pro** - Text-to-video and image-to-video generation with 3x faster rendering
## Key Features
* **Flexible Modes**: Supports text-to-video and image-to-video generation
* **Multiple Resolutions**: 720p and 1080p support
* **Duration Options**: 5 or 10 seconds
* **Fast Rendering**: 3x faster than standard Pro version
# Seedance 2 Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/seedance-2
api-manual/video-series/seedance-2.json POST /api/generate/submit
Text-to-video, first and last frame, and multimodal reference generation with Seedance 2 and Seedance 2 Fast
1. After submission, a `task_id` is returned immediately. If you provide a `callback_url`, Vidgo sends a POST request to that URL when the task reaches `finished` or `failed`.
2. You can always fetch the latest task result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Seedance 2 Video Generation
Seedance 2 is ByteDance's multimodal video family for API-based generation. On Vidgo API, you can choose between **seedance-2** for higher fidelity and **seedance-2-fast** for lower-latency generation, while keeping a single submit and status workflow.
## Available Models
* **seedance-2**: Higher-quality video generation with multimodal references and native audio support
* **seedance-2-fast**: Faster generation path with the same submit schema and lower per-second pricing
## Supported Workflows
* **Text to Video**: Generate directly from a prompt
* **First and Last Frame**: Guide motion between one or two frame anchors via `image_urls`
* **Multimodal Reference**: Add reference images, videos, and audio through `reference_image_urls`, `reference_video_urls`, and `reference_audio_urls`
## Input Rules
* `resolution`: `seedance-2` supports `480p`, `720p`, `1080p`, and `4k`; `seedance-2-fast` supports `480p` and `720p`
* `duration` accepts integer values from `4` to `15`
* `image_urls` supports up to `2` items
* `image_urls` is mutually exclusive with all `reference_*_urls` fields
* `reference_image_urls` supports up to `9` items; `reference_video_urls` and `reference_audio_urls` each support up to `3` items
* `reference_audio_urls` requires at least one `reference_image_urls` or `reference_video_urls` item
* Total reference inputs across image, video, and audio fields can contain at most `12` files
* `aspect_ratio` supports `auto`, `1:1`, `21:9`, `4:3`, `3:4`, `16:9`, and `9:16`
* `generate_audio`, `return_last_frame`, and `web_search` are optional boolean controls
## Seedance 2 vs Seedance 1.5 Pro vs Seedance 1.0 Pro
* **Seedance 2** adds multimodal reference image, video, and audio guidance with first and last frame control in one API shape.
* **Seedance 1.5 Pro** focuses on high-quality text-to-video and image-to-video generation with optional audio but without the same multimodal reference set.
* **Seedance 1.0 Pro** remains a strong option for earlier Seedance workflows, but Seedance 2 expands creative control and API flexibility for newer production pipelines.
# Sora 2 Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/sora-2
api-manual/video-series/sora-2.json POST /api/generate/submit
Standard quality video generation
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Sora 2 Video Generation
Generate standard quality videos using OpenAI's Sora 2 model. Supports text-to-video and image-to-video generation.
## Available Models
* **sora-2** - Standard quality video generation
* **sora-2-private** - Private deployment for standard quality
## Duration Options
* **10 seconds** - Short video clips
* **15 seconds** - Standard duration
## Advanced Parameters
### Style
Control the visual aesthetic of your generated videos with predefined styles:
* `thanksgiving` - Thanksgiving style
* `comic` - Comic style
* `news` - News style
* `selfie` - Selfie style
* `nostalgic` - Nostalgic/Retro style
* `anime` - Anime style
### Storyboard
Enable storyboard mode for finer control over video generation details. Set to `true` to enable or `false` to disable.
# Sora 2 Official
Source: https://docs.vidgo.ai/api-manual/video-series/sora-2-official
api-manual/video-series/sora-2-official.json POST /api/generate/submit
Text-to-video and optional image-guided video generation
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Sora 2 Official
`sora-2-official` supports text-to-video generation and optional single-image guided generation with fixed 4s, 8s, 12s, 16s, and 20s durations.
## Available Model
* **sora-2-official** - Text-to-video with optional reference image
## Required Parameters
* **prompt**: Text prompt for video generation
## Optional Parameters
* **duration**: `4`, `8`, `12`, `16`, or `20`. Default is `4`
* **aspect\_ratio**: `16:9` or `9:16`. Default is `16:9`
* **image\_urls**: Optional reference image array. Maximum `1` image
## Notes
* `image_urls` is optional. If provided, only one image is supported.
* This page only describes the unified submit request. Query status through the standard task status API.
# Sora 2 Pro Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/sora-2-pro
api-manual/video-series/sora-2-pro.json POST /api/generate/submit
Premium HD quality video generation
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Sora 2 Pro Video Generation
Generate premium HD quality videos using OpenAI's Sora 2 Pro model. Supports text-to-video and image-to-video generation with longer duration options.
## Available Models
* **sora-2-pro** - Premium HD quality video generation
* **sora-2-pro-private** - Private deployment for premium quality
## Duration Options
* **15 seconds** - HD quality
* **25 seconds** - Extended HD duration
## Advanced Parameters
### Style
Control the visual aesthetic of your generated videos with predefined styles:
* `thanksgiving` - Thanksgiving style
* `comic` - Comic style
* `news` - News style
* `selfie` - Selfie style
* `nostalgic` - Nostalgic/Retro style
* `anime` - Anime style
### Storyboard
Enable storyboard mode for finer control over video generation details. Set to `true` to enable or `false` to disable.
# Sora 2 Pro Official
Source: https://docs.vidgo.ai/api-manual/video-series/sora-2-pro-official
api-manual/video-series/sora-2-pro-official.json POST /api/generate/submit
Pro text-to-video and image-guided video generation with resolution-based billing
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Sora 2 Pro Official
`sora-2-pro-official` supports text-to-video generation and optional single-image guided generation with fixed 4s, 8s, 12s, 16s, and 20s durations.
## Available Model
* **sora-2-pro-official** - Pro text-to-video and image-guided video generation
## Required Parameters
* **prompt**: Text prompt for video generation
## Optional Parameters
* **duration**: `4`, `8`, `12`, `16`, or `20`. Default is `4`
* **resolution**: `720p`, `1024p`, or `1080p`. Default is `1024p`
* **aspect\_ratio**: `16:9` or `9:16` for text-to-video; `auto`, `16:9`, or `9:16` for image-to-video. Default is `16:9` for text-to-video and `auto` for image-to-video
* **image\_urls**: Optional reference image array. Maximum `1` image
## Credit Billing
Billing is calculated from `duration` and `resolution`.
* `720p`: 48 credits per second
* `1024p`: 80 credits per second
* `1080p`: 112 credits per second
For example, an 8-second `1024p` video uses `640` credits.
## Notes
* `image_urls` is optional. If provided, only one image is supported.
* `aspect_ratio=auto` is only valid when `image_urls` is provided.
* Query status through the standard task status API.
# VEO 3.1 Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/veo-3-1
api-manual/video-series/veo-3-1.json POST /api/generate/submit
Fast and high-quality 8-second video generation with Google's VEO 3.1
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# VEO 3.1 Video Generation
Generate fast or high-quality 8-second videos with Google's VEO 3.1 model. Supports text-to-video and image-to-video generation.
## Available Models
* **veo3.1-fast** - Fast 8-second generation
* **veo3.1-quality** - High-quality 8-second generation
## Duration Options
* **8 seconds** - Fixed duration for all generations
## Key Features
* Asynchronous processing that returns a `task_id` for status tracking
* Supports text-to-video and image-to-video generation
* Supports up to 4k output resolution
* Generated video URLs are valid for 24 hours
## Advanced Parameters
### Generation Type
* `frame` - Frame-to-video (two images)
* `reference` - Reference image video (three images)
* If omitted, inferred by `image_urls` count: 2 images for `frame`, 3 images for `reference`
### Image URLs
* Supports up to 3 images
* Frame mode: first image is the start frame, second image is the end frame
* Maximum file size: 10MB
* Supported formats: .jpeg, .jpg, .png, .webp
### Resolution
* `720p` (default), `1080p`, or `4k`
# VEO 3.1 Official Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/veo-3-1-official
api-manual/video-series/veo-3-1-official.json POST /api/generate/submit
Official VEO 3.1 video generation with duration, audio control, and image-guided modes
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# VEO 3.1 Official Video Generation
Generate videos with the official VEO 3.1 model family through one async API. The generation models support text-to-video, image-to-video, first/last-frame video, and three-image reference generation depending on the selected model and input.
## Available Models
* **veo3.1-fast-official** - Fast official generation with `4`, `6`, or `8` second duration options
* **veo3.1-lite-official** - Lightweight official generation with lower per-second pricing
* **veo3.1-quality-official** - Higher-quality official generation with 4K support
## Input Modes
* No `image_urls`: text-to-video
* One image: image-to-video
* Two images: first/last-frame video. The first image is the start frame and the second image is the end frame
* Three images: reference generation. Use `generation_type: "reference"` and `duration: 8`
* `veo3.1-lite-official` supports at most two images and does not support `generation_type: "reference"`
## Parameters
* **model**: Required model identifier. Use `veo3.1-fast-official`, `veo3.1-lite-official`, or `veo3.1-quality-official`
* **prompt**: Required text prompt for video generation, up to `1000` characters
* **image\_urls**: Optional image URL array. Supports up to `3` public image URLs
* **generation\_type**: Optional `frame` or `reference`. If omitted, the mode is inferred from `image_urls`
* **duration**: `4`, `6`, or `8`. Default is `8`. Reference generation and `veo3.1-lite-official` with `resolution: "1080p"` support `8` only
* **aspect\_ratio**: `16:9` or `9:16`. `auto` is also supported for one-image and two-image workflows. Default is `16:9`
* **resolution**: `720p`, `1080p`, or `4k`. Default is `1080p`. `veo3.1-lite-official` does not support `4k`
* **sound**: Boolean audio switch. Default is `true`; set `false` for silent output
* **callback\_url**: Optional webhook URL for completion or failure notifications
## Pricing
Pricing is charged per generated second and varies by model, resolution, and whether audio is generated. See the model page for the current credit table.
# Wan 2.6 Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/wan-2-6
api-manual/video-series/wan-2-6.json POST /api/generate/submit
Multi-shot 1080p video generation with Alibaba Wan 2.6
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Wan 2.6 Video Generation
Wan 2.6 is Alibaba's latest video generation model family. It supports text-to-video, image-to-video, and video-to-video workflows with stable character identity, multi-shot composition, and 1080p output.
## Available Models
* **wan2.6-text-to-video** - Generate videos from text prompts
* **wan2.6-image-to-video** - Animate a reference image with a prompt
* **wan2.6-video-to-video** - Edit or restyle an input video using a prompt
## Key Features
* **Duration**: 5, 10, or 15 seconds (video-to-video up to 10 seconds)
* **Resolution**: 720p or 1080p
* **Multi-Shots**: Toggle multi-shot composition for cinematic transitions
* **Prompt Length**: Up to 5,000 characters
# Wan Animate Video Generation
Source: https://docs.vidgo.ai/api-manual/video-series/wan-animate
api-manual/video-series/wan-animate.json POST /api/generate/submit
AI-powered character animation and replacement based on Alibaba's Wan2.2-Animate model
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Wan Animate Video Generation
Wan Animate is powered by Alibaba's Wan2.2-Animate model, a 14B parameter open-source model for digital human video generation. It accurately captures facial expressions and body movements from a reference video and applies them to a target image, enabling seamless character animation and replacement with realistic lighting and color preservation.
## Available Models
* **wan-animate-replace** - Replace a character in a video with one from a source image while preserving expressions and movements
* **wan-animate-move** - Animate a character image using motion from a reference video
## Resolution Options
* **480p** - Standard definition (default)
* **580p** - Enhanced definition
* **720p** - HD quality
# Wan 2.2 Image-to-Video Fast
Source: https://docs.vidgo.ai/api-manual/video-series/wan2.2-image-to-video-fast
api-manual/video-series/wan2.2-image-to-video-fast.json POST /api/generate/submit
Fast image-to-video generation with Alibaba Wan 2.2 Fast
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Wan 2.2 Image-to-Video Fast
`wan2.2-image-to-video-fast` animates one reference image, and optionally uses a second image as the last frame for stronger transition control.
## Available Model
* **wan2.2-image-to-video-fast** - Animate a reference image into a short video
## Key Parameters
* **Image URLs**: 1 required, up to 2 supported
* **Resolution**: `480p` or `720p`
* **Seed**: optional integer for reproducible outputs
# Wan 2.2 Text-to-Video Fast
Source: https://docs.vidgo.ai/api-manual/video-series/wan2.2-text-to-video-fast
api-manual/video-series/wan2.2-text-to-video-fast.json POST /api/generate/submit
Fast text-to-video generation with Alibaba Wan 2.2 Fast
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Wan 2.2 Text-to-Video Fast
`wan2.2-text-to-video-fast` is optimized for fast text-to-video generation with supported portrait and landscape output options.
## Available Model
* **wan2.2-text-to-video-fast** - Generate short videos from text prompts
## Key Parameters
* **Aspect Ratio**: `16:9`, `9:16`
* **Resolution**: `480p` or `720p`
* **Seed**: optional integer for reproducible outputs
# Wan 2.5 Image-to-Video
Source: https://docs.vidgo.ai/api-manual/video-series/wan2.5-image-to-video
api-manual/video-series/wan2.5-image-to-video.json POST /api/generate/submit
Image-to-video generation with Alibaba Wan 2.5
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Wan 2.5 Image-to-Video
`wan2.5-image-to-video` is a higher-quality single-image animation model with broader resolution support than the Wan 2.2 fast line.
## Available Model
* **wan2.5-image-to-video** - Animate a single image into a video clip
## Key Parameters
* **Image URLs**: exactly 1 required
* **Resolution**: `480p`, `720p`, or `1080p`
* **Duration**: `5` or `10` seconds
* **Optional Controls**: `audio`, `negative_prompt`, `seed`
# Wan 2.5 Text-to-Video
Source: https://docs.vidgo.ai/api-manual/video-series/wan2.5-text-to-video
api-manual/video-series/wan2.5-text-to-video.json POST /api/generate/submit
Text-to-video generation with Alibaba Wan 2.5
1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](/api-manual/task-management/status) endpoint.
# Wan 2.5 Text-to-Video
`wan2.5-text-to-video` is the text-only branch of the Wan 2.5 video family and supports multiple size presets with 5s and 10s generation lengths.
## Available Model
* **wan2.5-text-to-video** - Generate a video clip from a text prompt
## Key Parameters
* **Aspect Ratio**: `832*480`, `480*832`, `1280*720`, `720*1280`, `1920*1080`, `1080*1920`
* **Duration**: `5` or `10` seconds
* **Optional Controls**: `audio` string, `negative_prompt`, `seed`
## Notes
* If `audio` is provided, it must be a string. Do not send a boolean value.
# FAQs
Source: https://docs.vidgo.ai/faqs
Frequently asked questions about Vidgo API
# Frequently Asked Questions
Everything you need to know before you ship.
Vidgo API is an AI infrastructure platform 80% cheaper than fal.ai. It gives you unified access to top AI models with one key, predictable pricing, and production-ready reliability.
Create an account and generate your API key instantly from the dashboard.
New accounts receive free credits so you can test models before scaling.
We support leading image, video, and music models, with new additions every week.
Yes. Contact our team to discuss custom pricing, SLAs, and dedicated support.
We partner with multiple premium channels to secure highly competitive rates. Unlike fal.ai, we don't have operational overhead or advertising expenses, allowing us to pass these savings directly to our users.
Nano Banana Pro: 1K/2K resolution at $0.03 (80% cheaper than fal.ai's $0.15), 4K at $0.03 (90% cheaper than fal.ai's $0.30). Sora 2: 10s video at $0.05 (95% cheaper than fal.ai's $1.00), 15s at $0.05 (95% cheaper than fal.ai's $1.50). All prices include audio generation.
We use Suno's official models, including the latest v5 model. Our music API supports generating tracks up to 8 minutes long with professional quality.
No. We have transparent pricing and only charge for successful generations. Failed requests will automatically refund your credits.
We support multiple payment methods including Stripe (credit/debit cards), WeChat Pay, and cryptocurrency payments for maximum flexibility.
You can reach us at [support@vidgo.ai](mailto:support@vidgo.ai). We're also gradually launching additional support channels like Discord - stay tuned for announcements on our website.