dynamicads 2.0.0

Official Python SDK for DynamicAds API

DynamicAds Python SDK

Official Python SDK for the DynamicAds API.

Installation

pip install dynamicads

Quick Start

from dynamicads import DynamicAdsClient

# Initialize the client
client = DynamicAdsClient('your-api-key')

# Generate a new ad
ad = client.generate(
    prompt='Create a dynamic product showcase',
    media_type='video',
    dimensions={'width': 672, 'height': 384}
)

# Wait for completion
completed_ad = client.wait_for_completion(ad.id)
print(f"Ad generated: {completed_ad.media_url}")

Features

• Generate video and image ads
• Track generation status
• List all your ads
• Monitor API usage
• Type hints for better IDE support
• Comprehensive error handling

Examples

Generate an Ad

# Start generation
ad = client.generate(
    prompt='Create a dynamic product showcase',
    media_type='video',
    dimensions={'width': 672, 'height': 384}
)

# Wait for completion with custom timeout
try:
    completed_ad = client.wait_for_completion(
        ad.id,
        timeout=600,  # 10 minutes
        interval=5    # Check every 5 seconds
    )
    print(f"Media URL: {completed_ad.media_url}")
    print(f"Voice URL: {completed_ad.voice_url}")
    print(f"Component Code: {completed_ad.component_code}")
except DynamicAdsTimeoutError:
    print("Generation timed out")

List All Ads

# Get all ads
ads = client.list_ads()
for ad in ads:
    print(f"Ad {ad.id}: {ad.status}")
    if ad.is_complete:
        print(f"  Media URL: {ad.media_url}")

Check Usage

# Get usage info
usage = client.get_usage()
print(f"Used {usage.current_usage} out of {usage.limit} credits")

Error Handling

from dynamicads.exceptions import (
    DynamicAdsError,
    DynamicAdsTimeoutError,
    DynamicAdsAuthError,
    DynamicAdsRateLimitError,
    DynamicAdsValidationError
)

try:
    ad = client.generate(prompt='Create an ad')
except DynamicAdsAuthError:
    print("Invalid API key")
except DynamicAdsRateLimitError:
    print("Rate limit exceeded")
except DynamicAdsValidationError:
    print("Invalid request parameters")
except DynamicAdsTimeoutError:
    print("Operation timed out")
except DynamicAdsError as e:
    print(f"Other error: {e}")

API Reference

Configuration

client = DynamicAdsClient(
    api_key='your-api-key',  # Required
    base_url='https://api.dynamicads.dev/api',  # Optional
    debug=False  # Optional
)

Methods

generate(prompt, media_type='video', dimensions=None)

Generate a new ad with the given options.

• prompt: Description of the ad
• media_type: 'video' or 'image'
• dimensions: Dict with 'width' and 'height'

get_ad(id)

Get details of a specific ad.

list_ads()

List all ads associated with your API key.

get_usage()

Get current usage information.

wait_for_completion(id, timeout=300, interval=2)

Wait for an ad to complete generation.

• timeout: Max time to wait in seconds
• interval: Check interval in seconds

Response Types

Ad Object

@dataclass
class Ad:
    id: str
    status: str  # 'processing', 'complete', or 'error'
    media_url: Optional[str]
    voice_url: Optional[str]
    component_code: Optional[str]
    voice_script: Optional[str]
    prompt: str
    dimensions: AdDimensions
    media_type: str
    error: Optional[str]
    created_at: Optional[str]

Usage Object

@dataclass
class Usage:
    current_usage: int
    limit: int

Development

To contribute to the SDK:

1. Clone the repository
2. Install development dependencies:

   pip install -e ".[dev]"
   

3. Run tests:

   pytest
   

License

MIT