Docs
V1 Beta

Typical Workflow

To generate a video using the DigitalCarbon API v1-beta, follow these steps:

  1. Initiate Video Generation Process
  2. Check Generation Status
  3. Retrieve Results
  4. Optional: Upload Video to Custom URL

Initiate Video Generation Process

POST /v1-beta/generate-video

Initiates the video generation process using the provided image URLs and template parameters.

Examples

import requests
 
url = "https://api.digitalcarbon.ai/v1-beta/generate-video"
headers = {
    "X-API-Key": "your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "files": [
        {"url": "https://example.com/image1.jpg"},
        {"url": "https://example.com/image2.jpg"}
    ],
    "template_params": {
        "template_id": "ActiveListing1",
        "aspect_ratio": "1:1",
        "soundtrack_url": "https://example.com/music.mp3",
        "logo_url": "https://example.com/logo.png",
        "property_details": {
            "address": "123 Main St",
            "price": "$500,000",
            "details": "3 bed, 2 bath"
        },
        "contact_details": {
            "name": "John Doe",
            "phone": "(555) 123-4567",
            "website": "www.example.com"
        }
    }
}
 
response = requests.post(url, headers=headers, json=data)
print(response.json())
Request Headers
  • X-API-Key: Your API key.
  • Content-Type: application/json
Request Body
  • files: An array of objects, each containing:
    • url: The URL of an image to be used in the video generation.
  • template_params: An object containing:
    • template_id: The ID of the template to use for video generation.
    • aspect_ratio (optional): The desired aspect ratio of the output video. Possible values:
      • "16:9" (Landscape)
      • "1:1" (Square, default)
      • "4:5" (Portrait)
      • "9:16" (Vertical)
    • soundtrack_url (optional): URL of the audio file to be used as soundtrack.
    • logo_url (optional): URL of the logo to be displayed in the video.
    • property_details (optional): Object containing:
      • address (optional): Property address
      • price (optional): Property price
      • details (optional): Additional property details
    • contact_details (optional): Object containing:
      • name (optional): Contact person's name
      • phone (optional): Contact phone number
      • website (optional): Contact website
Response
  • 200 OK: { "job_id": "unique_job_id" }
  • 400 Bad Request:
    • { "detail": "Maximum of 100 photos allowed" }
    • { "detail": "Invalid image URLs: [list of invalid URLs]" }
  • 401 Unauthorized: { "detail": "API Key is missing or invalid" }
  • 500 Internal Server Error: { "detail": "An internal error occurred" }

Check Generation Status

GET /v1-beta/generate-video/{job_id}/status

Checks the status of a video generation job.

Examples

import requests
 
job_id = "unique_job_id"
url = f"https://api.digitalcarbon.ai/v1-beta/generate-video/{job_id}/status"
headers = {
    "X-API-Key": "your_api_key_here"
}
 
response = requests.get(url, headers=headers)
print(response.json())
Response
  • 200 OK: { "status": "job_status" }
    • job_status can be one of:
      • queued: Job is waiting to be processed
      • processing: Job is being processed
      • completed: Job finished successfully
      • failed: Job failed (includes error_message if available)
  • 400 Bad Request: { "detail": "Invalid job ID format" }
  • 401 Unauthorized: { "detail": "API Key is missing or invalid" }
  • 404 Not Found: { "detail": "Job not found" }

Retrieve Results

GET /v1-beta/generate-video/{job_id}/results

Retrieves the results of a completed video generation job.

Examples

import requests
 
job_id = "unique_job_id"
url = f"https://api.digitalcarbon.ai/v1-beta/generate-video/{job_id}/results"
headers = {
    "X-API-Key": "your_api_key_here"
}
 
response = requests.get(url, headers=headers)
print(response.json())
Response
  • 200 OK: Returns the job response data
  • 400 Bad Request: { "detail": "Job is not completed yet" }
  • 401 Unauthorized: { "detail": "API Key is missing or invalid" }
  • 404 Not Found: { "detail": "Job not found" }
  • 500 Internal Server Error: { "detail": "Job completed but no results found" }

Upload Video Result

POST /v1-beta/generate-video/{job_id}/results/upload-video

Uploads the generated video to a specified URL.

Examples

import requests
 
job_id = "unique_job_id"
url = f"https://api.digitalcarbon.ai/v1-beta/generate-video/{job_id}/results/upload-video"
headers = {
    "X-API-Key": "your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "upload_url": "https://your-upload-destination.com/video-upload-url"
}
 
response = requests.post(url, headers=headers, json=data)
print(response.json())
Request Body
  • upload_url: The URL where the generated video should be uploaded.
Response
  • 200 OK: { "message": "Video uploaded successfully" }
  • 400 Bad Request: { "detail": "Job is not completed yet" }
  • 401 Unauthorized: { "detail": "API Key is missing or invalid" }
  • 404 Not Found: { "detail": "Job not found" }
  • 500 Internal Server Error: Various error messages depending on the specific error

Limitations

  • Image Limit: Maximum 100 photos per request
  • Image Formats: Supported formats are JPG, JPEG, PNG, and WebP
  • Aspect Ratios: Supports 16:9, 1:1 (default), 4:5, and 9:16
  • Video Duration: Fixed at 30 seconds (customization coming in future updates)
  • Processing Time: Video generation typically takes 15-20 minutes

Notes

  • The API is currently in beta (v1-beta) and may undergo changes
  • Store your API key securely and never share it publicly
  • All image URLs must be publicly accessible
  • The video upload endpoint requires proper write permissions at the destination URL
V0 Beta (Legacy)