API Platform Console

๐Ÿ”—Get Started

For State-of-the-Art AI Actor Model Gaga-1

We offer the industry-leading Gaga-1, a Sota-level AI actor model with cinematic-grade performance capabilitiesโ€”featuring precise lip-sync, nuanced emotional expression, and multi-character interactive scenes. For inquiries or collaborations, please log in via the official platform: https://platform.gaga.art, or contact us at business@sand.ai.

For Digital Human Model Gaga-avatar

To access the Gaga-avatar digital human model, please log in via the official platform: https://platform.gaga.art.

๐Ÿ”—Account

When accessing the Platform through https://platform.gaga.art, if you are not logged in, you will be automatically redirected to the login page. The accounts for the Platform and Gaga are interconnected, and you can directly use your Gaga account to log in to the open platform. However, the account management is separate. That is to say, if a Gaga account is blocked for violating the user policy, it will not affect the normal use of the Platform, and vice versa.

๐Ÿ”—Buy credits

After login successfully, you can purchase credits package via https://platform.gaga.art/app/buy-credits. The billing for Gaga accounts and the open platform accounts is also separate. The open API calls will not consume the credits of Gaga accounts, and vice versa.

You can visit https://platform.gaga.art/app/general to view the remaining credits of current account and the consumption in the past 30 days.

๐Ÿ”—Authorization

๐Ÿ”—Create API Key

After login successfully, you can access the API Key management page via https://platform.gaga.art/app/keys. Click the "Create API Key" button to start creating an API Key. You must specify a name to help you remember the purpose of the API Key. Then click the " Confirm" button to submit the request.

The newly created API Key will be displayed on the page, and it will only be shown once.You need to copy it and save it properly in the configuration file of your own project.

For security reasons, it is recommended that you regularly delete existing API Keys and create new ones.

ๅฎ˜็ฝ‘

๐Ÿ”—Use API Key

After successfully obtaining the API Key, you can complete the Authentication by adding the API Key through the Authorization HTTP Header when calling the open API.

Request Header Format:

Authorization: Bearer YOUR_API_KEY

API Endpoint:

https://api.gaga.art/v1/generations

๐Ÿ’ก Tip: If you need to use digital human images or audio files, you need to upload files first through the upload asset API to get the resource ID, then use it in your API calls.

๐Ÿ”—Step 1: Upload Asset (Optional)

If you need to use digital human images or audio files in your video generation, you must first upload them through the upload asset API to get the resource ID.

๐Ÿ”—API Endpoint

POST https://api.gaga.art/v1/assets

Supported File Formats:

  • Images: JPEG, PNG, GIF, WebP
  • Videos: MP4
  • Audio: MP3, WAV, OGG

Request Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

๐Ÿ”—Method 1: Upload Local File

If you have a local file, you can upload it directly:

cURL Example:

curl -X POST "https://api.gaga.art/v1/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/your/file.jpg"

Python Example:

import requests

url = "https://api.gaga.art/v1/assets"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
files = {
    "file": open("/path/to/your/file.jpg", "rb")
}

response = requests.post(url, headers=headers, files=files)
result = response.json()
print(f"Asset ID: {result.get('id')}")

๐Ÿ”—Method 2: Upload from URL

If you only have an image URL (e.g., from the web), you need to download it first and then upload it:

Python Example:

import requests
from io import BytesIO

def upload_asset_from_url(image_url, api_key):
    """
    Download an image from URL and upload it as an asset.
    
    Args:
        image_url: The URL of the image to download
        api_key: Your API key
    
    Returns:
        Asset ID if successful
    """
    # Step 1: Download the image from URL
    image_response = requests.get(image_url)
    image_response.raise_for_status()  # Raise an error for bad status codes
    
    # Step 2: Get the filename from URL or use a default
    filename = image_url.split("/")[-1].split("?")[0] or "image.jpg"
    
    # Step 3: Upload the image to our API
    upload_url = "https://api.gaga.art/v1/assets"
    headers = {
        "Authorization": f"Bearer {api_key}"
    }
    files = {
        "file": (filename, BytesIO(image_response.content), image_response.headers.get("content-type", "image/jpeg"))
    }
    
    upload_response = requests.post(upload_url, headers=headers, files=files)
    upload_response.raise_for_status()
    
    result = upload_response.json()
    asset_id = result.get("id")
    print(f"Successfully uploaded asset. Asset ID: {asset_id}")
    return asset_id

# Usage example
api_key = "YOUR_API_KEY"
image_url = "https://example.com/image.jpg"
asset_id = upload_asset_from_url(image_url, api_key)

JavaScript/Node.js Example:

const fetch = require('node-fetch');
const FormData = require('form-data');
const fs = require('fs');

async function uploadAssetFromUrl(imageUrl, apiKey) {
    // Step 1: Download the image
    const imageResponse = await fetch(imageUrl);
    if (!imageResponse.ok) {
        throw new Error(`Failed to download image: ${imageResponse.statusText}`);
    }
    
    const imageBuffer = await imageResponse.buffer();
    const contentType = imageResponse.headers.get('content-type') || 'image/jpeg';
    const filename = imageUrl.split('/').pop().split('?')[0] || 'image.jpg';
    
    // Step 2: Upload to our API
    const formData = new FormData();
    formData.append('file', imageBuffer, {
        filename: filename,
        contentType: contentType
    });
    
    const uploadResponse = await fetch('https://api.gaga.art/v1/assets', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${apiKey}`,
            ...formData.getHeaders()
        },
        body: formData
    });
    
    if (!uploadResponse.ok) {
        throw new Error(`Upload failed: ${uploadResponse.statusText}`);
    }
    
    const result = await uploadResponse.json();
    console.log(`Successfully uploaded asset. Asset ID: ${result.id}`);
    return result.id;
}

// Usage
const apiKey = 'YOUR_API_KEY';
const imageUrl = 'https://example.com/image.jpg';
uploadAssetFromUrl(imageUrl, apiKey)
    .then(assetId => console.log('Asset ID:', assetId))
    .catch(error => console.error('Error:', error));

๐Ÿ”—Response

Response Format:

{
  "id": 123
}

Response Fields:

  • id (integer): The asset ID that you can use in subsequent API calls. For example, use it in the source.content field when generating videos.

๐Ÿ”—Get Asset Details

You can retrieve asset information by asset ID:

API Endpoint:

GET https://api.gaga.art/v1/assets/{asset_id}

cURL Example:

curl -X GET "https://api.gaga.art/v1/assets/123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python Example:

import requests

asset_id = 123
url = f"https://api.gaga.art/v1/assets/{asset_id}"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
result = response.json()
print(result)

Response:

{
  "id": 123,
  "url": "https://example.com/asset/image.jpg"
}

Response Fields:

  • id (integer): The asset ID
  • url (string): The URL of the asset file

๐Ÿ’ก Note: We are currently developing an Asset Page that will allow you to view and manage all your uploaded assets through the platform interface. Once available, you'll be able to browse, search, and manage your assets more easily.

๐Ÿ”—Step 2: Submit Generation Request

After uploading assets (if needed), you can submit a video generation request. Here are examples for different models:

๐Ÿ”—Example 1: Using Gaga-1 Model

Gaga-1 is an industry-leading AI actor model that supports precise lip-sync, nuanced emotional expression, and multi-character interactive scenes.

Supported Model: gaga-1

Requirements:

  • โš ๏ธ Optional: Digital human image (via source parameter)
  • โš ๏ธ Optional: Audio content (via audio type in conditions)
  • โœ… Required: Character dialogue (via text type in conditions)
curl -X POST "https://api.gaga.art/v1/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gaga-1",
    "resolution": "720p",
    "aspectRatio": "16:9",
    "source": {
      "type": "image",
      "content": "747324435023237"
    },
    "chunks": [{
      "duration": 10,
      "conditions": [{
        "type": "text",
        "content": "Hello, World!"
      }]
    }],
    "enablePromptEnhancement": true
  }'

Python Example:

import requests

url = "https://api.gaga.art/v1/generations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "gaga-1",
    "resolution": "720p",
    "aspectRatio": "16:9",
    "source": {
      "type": "image",
      "content": "747324435023237"
    },
    "chunks": [{
      "duration": 10,
      "conditions": [{
        "type": "text",
        "content": "Hello, World!"
      }]
    }],
    "enablePromptEnhancement": true
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

Response:

{
  "id": 123456789
}

The returned id is the task ID that you can use to query the generation status.

๐Ÿ“š For other parameters: Please refer to the complete API documentation for the generation endpoint details to learn about all available parameters.

๐Ÿ”—Example 2: Using Gaga-avatar Model

Gaga-avatar is a digital human model that can generate realistic digital human videos.

Supported Models: avatar-h1 or avatar-h1-pro

Requirements:

  • โœ… Required: Upload digital human image (via source parameter)
  • โœ… Required: Provide audio content (via audio type in conditions)
  • โš ๏ธ Optional: Use text to shape character emotions and actions (via text type in conditions)
curl -X POST "https://api.gaga.art/v1/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "avatar-h1-pro",
    "resolution": "720p",
    "seed": 12345,
    "aspectRatio": "16:9",
    "source": {
      "type": "image",
      "content": 123
    },
    "chunks": [{
      "duration": 5,
      "conditions": [
        {
          "type": "audio",
          "content": "11232355"
        },
        {
          "type": "text",
          "content": "smile, wave"
        }
      ],
      "enablePromptEnhancement": true
    }]
  }'

Python Example:

import requests

url = "https://api.gaga.art/v1/generations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "avatar-h1-pro",
    "resolution": "720p",
    "seed": 12345,
    "aspectRatio": "16:9",
    "source": {
        "type": "image",
        "content": 123
    },
    "chunks": [{
        "duration": 5,
        "conditions": [
            {
                "type": "audio",
                "content": "11232355"
            },
            {
                "type": "text",
                "content": "smile, wave"
            }
        ],
        "enablePromptEnhancement": True
    }]
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

Response:

{
  "id": 123456789
}

The returned id is the task ID that you can use to query the generation status.

๐Ÿ“š For other parameters: Please refer to the complete API documentation for the generation endpoint details to learn about all available parameters.

๐Ÿ”—Step 3: Get Generation Results

After calling the generation API, you will receive a response containing a task ID. Video generation is asynchronous, so you need to query the generation status using the task ID.

๐Ÿ”—Query Task Status

Use the task ID to query generation progress and results:

curl -X GET "https://api.gaga.art/v1/generations/{TASK_ID}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python Example:

import requests
import time

# Assume you have obtained the task ID (from the response of the generation API call)
task_id = "YOUR_TASK_ID"
url = f"https://api.gaga.art/v1/generations/{task_id}"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

# Poll for task status
while True:
    response = requests.get(url, headers=headers)
    result = response.json()
    
    if result.get("status") == "Success":
        print("Generation completed!")
        print(f"Video URL: {result.get('resultVideoURL')}")
        break
    elif result.get("status") == "Fail":
        print("Generation failed")
        break
    else:
        print(f"Generating... Status: {result.get('status')}")
        time.sleep(2)  # Wait 2 seconds before querying again

Response:

{
  "id": 123456789,
  "status": "Success",
  "resultVideoURL": "https://example.com/video.mp4",
  "resultVideoId": 987654321,
  "createTime": "2024-01-01T00:00:00Z"
}

Status Values:

  • PreProcessing: The task is being preprocessed
  • Pending: The task is waiting to be processed
  • Running: The task is currently being processed
  • Success: The task completed successfully
  • Fail: The task failed
  • Canceled: The task was canceled

When the status is Success, the resultVideoURL field contains the URL of the generated video.

๐Ÿ“š For details: Please refer to the complete API documentation to learn about all possible task status values and response formats.

๐Ÿ”—Next Steps

๐Ÿ”—FAQ

๐Ÿ”—Authentication Errors

Error: 401 Unauthorized or Invalid API Key

Solutions:

  • Verify that your API Key is correct and properly formatted
  • Ensure you're using Bearer YOUR_API_KEY format in the Authorization header
  • Check if your API Key has been deleted or expired. Create a new one from the API Keys page
  • Make sure there are no extra spaces or newlines in your API Key

๐Ÿ”—Insufficient Credits

Error: Insufficient credits or Account balance is zero

Solutions:

  • Check your account balance on the General page
  • Purchase credits from the Buy Credits page
  • Note that API credits and Gaga account credits are separate

๐Ÿ”—Asset Upload Failures

Error: File upload failed or Invalid file format

Solutions:

  • Verify that your file format is supported (Images: JPEG, PNG, GIF, WebP; Videos: MP4; Audio: MP3, WAV, OGG)
  • When uploading from URL, verify the URL is accessible and returns a valid image/audio/video file
  • Ensure the file is not corrupted

๐Ÿ”—Generation Task Failures

Error: Generation failed or task status returns Fail

Solutions:

  • Check the error message in the API response for specific failure reasons
  • Verify that all required parameters are provided (e.g., source for Gaga-avatar model, chunks with valid conditions)
  • Ensure the asset IDs used in your request are valid (use GET /v1/assets/{id} to verify)
  • For Gaga-avatar model, ensure both image (source) and audio are provided

๐Ÿ”—Invalid Request Parameters

Error: 422 Validation Error or Invalid parameter

Solutions:

  • Review the complete API documentation for required and optional parameters
  • Verify parameter formats (e.g., model names, resolution values, aspect ratios)
  • Check that JSON structure matches the expected schema

๐Ÿ”—Still Having Issues?

If you're still experiencing issues:

Happy coding! ๐ŸŽ‰

Get Started
Account
Buy credits
Authorization
Create API Key
Use API Key
Step 1: Upload Asset (Optional)
API Endpoint
Method 1: Upload Local File
Method 2: Upload from URL
Response
Get Asset Details
Step 2: Submit Generation Request
Example 1: Using Gaga-1 Model
Example 2: Using Gaga-avatar Model
Step 3: Get Generation Results
Query Task Status
Next Steps
FAQ
Authentication Errors
Insufficient Credits
Asset Upload Failures
Generation Task Failures
Invalid Request Parameters
Still Having Issues?
API Platform for Gaga AI - State-of-the-Art AI Actor & Digital Human Models