⚠️ Deprecation Notice

This is a legacy API version that will be deprecated soon. For new implementations, please use our latest API version (v1-beta) instead.

Typical Workflow

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

1. Initiate Video Generation Process
2. Check Generation Status
3. Retrieve Results

Initiate Video Generation Process

POST /v0-beta/generate-video

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

Examples

import requests
 
url = "https://api.digitalcarbon.ai/v0-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.png"}
    ],
    "soundtrack": "https://example.com/music.mp3",
    "overlay_texts": ["Text 1", "Text 2"],
    "aspect_ratio": "16:9",
    "duration": "30",
    "model": "gen_2",
    "branding": {
        "logo_url": "https://example.com/logo.png",
        "text": [
            {"order": 1, "content": "Brand Text 1"},
            {"order": 2, "content": "Brand Text 2"}
        ]
    }
}
 
response = requests.post(url, headers=headers, json=data)
print(response.json())

Notes:

1. Each image contributes approximately 3 seconds to the video duration.
2. If the number of provided images would result in a video longer than the specified duration, our API will automatically select the best images to fit within the allowed duration.
3. If there are fewer images than needed to reach the specified duration, the resulting video will be shorter than the requested duration.
4. The branding elements will be stacked vertically in the following order:
   • Logo (if provided)
   • Text items, arranged according to their order value

Check Generation Status

GET /v0-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/v0-beta/generate-video/{job_id}/status"
headers = {
    "X-API-Key": "your_api_key_here"
}
 
response = requests.get(url, headers=headers)
print(response.json())

Retrieve Results

GET /v0-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/v0-beta/generate-video/{job_id}/results"
headers = {
    "X-API-Key": "your_api_key_here"
}
 
response = requests.get(url, headers=headers)
print(response.json())

Upload Video Result

POST /v0-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/v0-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())

Notes:

1. This endpoint should be called after the job status is "completed".
2. The upload_url should be a valid URL where you have permission to upload files.
3. The video will be uploaded with the content type video/mp4.

Limitations

• Image Limit: The API currently accepts a maximum of 100 photos per video generation request. The best photos to represent the property will be chosen automatically to fit within the duration of the video.
• Processing Time: Video generation typically takes 15-20 minutes to complete. This duration may vary based on complexity and server load.
• Image Format: Supported formats include JPEG, PNG, and WebP.
• Aspect Ratio: The API supports four aspect ratios: 16:9 (Landscape), 1:1 (Square), 4:5 (Portrait), and 9:16 (Vertical).
• Video Duration:
  • The API supports video durations of 10, 20, 30, 40, 50, and 60 seconds, with 60 seconds being the default.
  • Each image contributes approximately 3 seconds to the video.
  • If the provided images would exceed the specified duration, the API will automatically select the best photos to represent the property within the allowed duration.
  • If there are fewer images than needed to reach the specified duration, the resulting video will be shorter than requested.
• Image Classification and Filtering:
  • The API automatically classifies uploaded images and may discard certain types of images that are not directly related to the property.
  • Images classified as "Miscellaneous" (e.g., floor plans, annotated images, maps, branding materials) may be excluded from the final video to focus on showcasing the property itself.
  • Specifically, images with map markers, custom drawings, text overlays, or annotations are likely to be classified as "Miscellaneous" and may not be included in the generated video.

Notes

• The API is currently in beta (v0-beta) and may undergo changes.
• Make sure to store your API key securely. Do not share it publicly.
• Our image classification system aims to prioritize images that best represent the property. This may result in some submitted images not appearing in the final video if they are deemed less relevant or not directly showcasing the property features.