AI Video API Documentation

Basic Information

Base URL: https://vibegen.art/api/v1

Authentication: Bearer Token (API Key)

All requests must include the API Key in the header:

Authorization: Bearer YOUR_API_KEY

1. Create Video Generation Task

Endpoint

POST /api/v1/generations

Request Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Parameters

Parameter	Type	Required	Description	Example
`model`	string	Yes	Model name	`"seedance 2.0"`
`prompt`	string	Yes	Video description text	`"A futuristic city with flying cars at sunset"`
`image_urls`	string[]	No	Reference image URLs array (required for image-to-video)	`["https://example.com/image.jpg"]`
`duration`	number	No	Video duration in seconds, default 5	`5` or `10`
`aspect_ratio`	string	No	Aspect ratio, default `"16:9"`	`"16:9"`, `"9:16"`, `"1:1"`, `"21:9"`, `"4:3"`, `"3:4"`, `"9:21"`, `"adaptive"`, `"keep_ratio"`
`resolution`	string	No	Resolution, default `"480p"`	`"480p"`, `"720p"`, `"1080p"`
`generate_audio`	boolean	No	Whether to generate video with audio, default false	`true` or `false`
`callback_url`	string	No	Callback URL after task completion	`"https://vibegen.art/webhook"`

Request Examples

Text-to-Video (No Audio)

curl -X POST https://vibegen.art/api/v1/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-video-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "seedance 2.0",
    "prompt": "Realistic style, under a clear blue sky, a large field of white daisies, camera gradually zooming in",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

Text-to-Video (With Audio)

curl -X POST https://vibegen.art/api/v1/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-video-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "seedance 2.0",
    "prompt": "A girl holding a fox, with wind and bird sounds audible",
    "duration": 5,
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

Image-to-Video

curl -X POST https://vibegen.art/api/v1/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-video-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "seedance 2.0",
    "prompt": "Girl opens her eyes, gently looks at the camera, hair blown by the wind",
    "image_urls": ["https://example.com/girl-with-fox.png"],
    "duration": 5,
    "aspect_ratio": "adaptive",
    "generate_audio": true
  }'

Response Examples

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "model": "seedance 2.0",
    "task_type": "text_to_video",
    "created_at": "2025-03-10T10:00:00Z"
  }
}

Error Response (400 Bad Request)

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Missing required parameters: model, prompt"
  }
}

Error Response (401 Unauthorized)

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key"
  }
}

Error Response (402 Payment Required)

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Required: 100, Available: 50"
  }
}

2. Query Task Status

Endpoint

GET /api/v1/tasks/{task_id}

Request Headers

Authorization: Bearer YOUR_API_KEY

Path Parameters

Parameter	Type	Required	Description
`task_id`	string	Yes	Task ID

Request Example

curl -X GET https://vibegen.art/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk-video-xxxxxxxxxxxxxxxx"

Response Examples

Task In Progress (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "model": "seedance 2.0",
    "task_type": "text_to_video",
    "prompt": "A futuristic city with flying cars at sunset",
    "video_url": null,
    "created_at": "2025-03-10T10:00:00Z",
    "completed_at": null,
    "error": null
  }
}

Task Completed (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "model": "seedance 2.0",
    "task_type": "text_to_video",
    "prompt": "A futuristic city with flying cars at sunset",
    "video_url": "https://cdn.example.com/videos/abc123.mp4",
    "created_at": "2025-03-10T10:00:00Z",
    "completed_at": "2025-03-10T10:02:30Z",
    "error": null
  }
}

Task Failed (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "model": "seedance 2.0",
    "task_type": "text_to_video",
    "prompt": "A futuristic city with flying cars at sunset",
    "video_url": null,
    "created_at": "2025-03-10T10:00:00Z",
    "completed_at": null,
    "error": "Content policy violation"
  }
}

Task Not Found (404 Not Found)

{
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found"
  }
}

3. Get Task List

Endpoint

GET /api/v1/tasks

Request Headers

Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Required	Description	Default
`status`	string	No	Filter by status: `pending`, `processing`, `completed`, `failed`	All
`limit`	number	No	Items per page	20
`offset`	number	No	Offset	0

Request Example

curl -X GET "https://vibegen.art/api/v1/tasks?status=completed&limit=10" \
  -H "Authorization: Bearer sk-video-xxxxxxxxxxxxxxxx"

Response Example (200 OK)

{
  "success": true,
  "data": {
    "tasks": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "completed",
        "model": "seedance 2.0",
        "task_type": "text_to_video",
        "prompt": "A futuristic city",
        "video_url": "https://cdn.example.com/videos/abc123.mp4",
        "created_at": "2025-03-10T10:00:00Z",
        "completed_at": "2025-03-10T10:02:30Z",
        "error": null
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 1,
      "total_pages": 1
    }
  }
}

4. Callback Notifications

If a callback_url is provided when creating a task, a POST request will be sent to that URL when the task completes or fails.

Callback Request

Request Headers

Content-Type: application/json

Request Body (Task Completed)

{
  "event": "task.completed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "video_url": "https://cdn.example.com/videos/abc123.mp4",
  "created_at": "2025-03-10T10:00:00Z",
  "completed_at": "2025-03-10T10:02:30Z"
}

Request Body (Task Failed)

{
  "event": "task.failed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error_message": "Content policy violation",
  "created_at": "2025-03-10T10:00:00Z",
  "failed_at": "2025-03-10T10:00:15Z"
}

5. Status Descriptions

Status	Description
`pending`	Task created, waiting for processing
`processing`	Task is being generated
`completed`	Task completed, video generated successfully
`failed`	Task failed

6. Error Codes

Error Code	HTTP Status	Description
`INVALID_API_KEY`	401	Invalid or missing API key
`INVALID_PARAMETER`	400	Invalid request parameters
`INSUFFICIENT_CREDITS`	402	Insufficient credits
`TASK_NOT_FOUND`	404	Task not found
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded
`PROVIDER_ERROR`	502	Third-party service error
`INTERNAL_ERROR`	500	Internal server error

7. Pricing

Seedance 2.0 credit pricing:

Resolution	Aspect Ratio	Duration	Credits (With Audio)	Credits (No Audio)
480p	All supported	5s	20	15
720p	All supported	5s	43	30
1080p	All supported	5s	90	50
480p	All supported	10s	40	25
720p	All supported	10s	86	45
1080p	All supported	10s	180	100

Notes:

Set generate_audio: true for videos with audio
Image-to-video costs the same as text-to-video
All aspect ratios have the same pricing

8. Limitations

Rate Limits

Maximum 1000 task creations per minute per API Key
Maximum 1000 queries per minute per API Key

Content Limits

prompt maximum length: 2000 characters
Supported video durations: 5 seconds or 10 seconds
Supported aspect ratios: 16:9, 9:16, 1:1, 21:9, 4:3, 3:4, 9:21, adaptive, keep_ratio
Supported resolutions: 480p, 720p, 1080p

Timeout

Video generation task timeout: 10 minutes
Task status will change to failed after timeout

9. SDK Examples

JavaScript/Node.js

const axios = require('axios');

const API_KEY = 'sk-video-xxxxxxxxxxxxxxxx';
const BASE_URL = 'https://vibegen.art/api/v1';

// Create video generation task
async function createVideoTask() {
  const response = await axios.post(`${BASE_URL}/generations`, {
    model: 'seedance 2.0',
    prompt: 'A futuristic city with flying cars at sunset',
    duration: 5,
    aspect_ratio: '16:9',
    resolution: '720p'
  }, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  return response.data.data.id;
}

// Query task status
async function getTaskStatus(taskId) {
  const response = await axios.get(`${BASE_URL}/tasks/${taskId}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  
  return response.data.data;
}

// Poll and wait for task completion
async function waitForCompletion(taskId) {
  while (true) {
    const task = await getTaskStatus(taskId);
    
    if (task.status === 'completed') {
      console.log('Video generation completed:', task.video_url);
      return task;
    } else if (task.status === 'failed') {
      console.error('Video generation failed:', task.error_message);
      throw new Error(task.error_message);
    }
    
    console.log('Task in progress...');
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
  }
}

// Usage example
(async () => {
  try {
    const taskId = await createVideoTask();
    console.log('Task created:', taskId);
    
    const result = await waitForCompletion(taskId);
    console.log('Final result:', result);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

Python

import requests
import time

API_KEY = 'sk-video-xxxxxxxxxxxxxxxx'
BASE_URL = 'https://vibegen.art/api/v1'

def create_video_task():
    """Create video generation task"""
    response = requests.post(
        f'{BASE_URL}/generations',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json'
        },
        json={
            'model': 'seedance 2.0',
            'prompt': 'A futuristic city with flying cars at sunset',
            'duration': 5,
            'aspect_ratio': '16:9',
            'resolution': '720p'
        }
    )
    response.raise_for_status()
    data = response.json()
    return data['data']['id']

def get_task_status(task_id):
    """Query task status"""
    response = requests.get(
        f'{BASE_URL}/tasks/{task_id}',
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    response.raise_for_status()
    data = response.json()
    return data['data']

def wait_for_completion(task_id):
    """Poll and wait for task completion"""
    while True:
        task = get_task_status(task_id)
        
        if task['status'] == 'completed':
            print(f"Video generation completed: {task['video_url']}")
            return task
        elif task['status'] == 'failed':
            raise Exception(f"Video generation failed: {task.get('error_message')}")
        
        print('Task in progress...')
        time.sleep(5)

# Usage example
if __name__ == '__main__':
    try:
        task_id = create_video_task()
        print(f'Task created: {task_id}')
        
        result = wait_for_completion(task_id)
        print(f'Final result: {result}')
    except Exception as e:
        print(f'Error: {e}')

10. Best Practices

1. Error Handling

Always check HTTP status codes
Handle all possible error responses
Implement retry mechanism (exponential backoff recommended)

2. Polling Strategy

Poll task status every 5-10 seconds
Set maximum poll count or timeout
Use callback URL instead of polling (recommended)

3. Performance Optimization

Be mindful of rate limits when creating tasks in batch
Cache completed task results
Use CDN to accelerate video access

4. Security Recommendations

Keep API Key secure, do not commit to code repository
Store API Key in environment variables
Rotate API Key regularly
Verify callback request signatures

11. FAQ

Q: How long does video generation take?

A: Typically 30-120 seconds, depending on the model, resolution, and server load.

Q: How long are generated videos saved?

A: The generated videos and returned video URLs are valid for 24 hours. Please download and save them locally within this period. After 24 hours, the video files will be permanently deleted.

Q: How to get an API Key?

A: Log in to the console and create a new key on the API Keys page.

Q: How to recharge credits?

A: Select a recharge package on the Billing page in the console.

Q: Which languages are supported for prompts?

A: Both Chinese and English are supported. Detailed descriptions are recommended for better results.

Q: How long can the generated videos be?

A: Currently supports 5 seconds and 10 seconds durations.

12. Contact Support

Technical Documentation: https://vibegen.art/docs
Email Support: [email protected]
Support System: https://vibegen.art

Version: v1.0
Last Updated: 2025-03-10