API Documentation

Media Access

Access generated media files (videos, GIFs, and audio).

Media files (GIFs, videos, and audio) are served directly from our CDN. The URLs are returned in the ad details response.

# Media URLs example
{
  "mediaUrl": "https://dynamicads.app/media/videos/2024/12/08/20241208230240_1733698960671.gif",
  "voiceUrl": "https://dynamicads.app/media/audio/2024/12/08/20241208230247_-1461271707.mp3"
}

Python SDK Installation

Install the DynamicAds Python SDK:

# Install using pip
pip install dynamicads

# Or using poetry
poetry add dynamicads

Python SDK Usage

Initialize and use the SDK:

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"Media URL: {completed_ad.media_url}")
print(f"Voice URL: {completed_ad.voice_url}")

# List all your ads
ads = client.list_ads()
for ad in ads:
    print(f"Ad {ad.id}: {ad.status}")

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

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

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

JavaScript SDK Installation

Add the DynamicAds JavaScript SDK to your web page:

<!-- Add our SDK script -->
<script src="https://dynamicads.app/sdk.js"></script>

JavaScript SDK Usage

Initialize and use the SDK:

// Using Web Components
// Just add our SDK script and use the components:
<dynamic-ad ad-id="your-ad-id"></dynamic-ad>
<dynamic-agent agent-id="your-agent-id"></dynamic-agent>

// Optional: Initialize with custom options
DynamicAds.init({
  debug: true, // Enable debug logging
  baseUrl: 'https://dynamicads.app/api' // Custom API endpoint
});

// Styling examples
<style>
  /* Ad container styles */
  .dynamic-ad-container {
    width: 100%;
    max-width: 320px;
    margin: 0 auto;
    border-radius: 0.75rem;
    overflow: hidden;
    background: rgb(17 24 39);
  }

  /* Agent container styles */
  .dynamic-agent-container {
    width: 320px;
    max-width: 320px;
    margin: 0 auto;
    position: relative;
  }

  .agent-preview {
    position: absolute;
    bottom: 15px;
    right: -290px;
    width: 250px;
    min-height: 150px;
    border-radius: 0.75rem;
    z-index: 100;
  }

  /* Mobile responsive styles */
  @media (max-width: 640px) {
    .agent-preview {
      position: relative;
      bottom: 0;
      right: 0;
      width: 100%;
      margin-top: 1rem;
    }
  }
</style>

// React Integration Example
import { useEffect, useRef } from 'react';

function DynamicAdsComponent() {
  const sdkRef = useRef<HTMLScriptElement | null>(null);

  useEffect(() => {
    // Clean up previous script if it exists
    if (sdkRef.current) {
      sdkRef.current.remove();
    }

    // Add SDK script
    const script = document.createElement('script');
    script.src = 'https://dynamicads.app/sdk.js';
    script.async = true;
    script.type = 'text/javascript';
    sdkRef.current = script;
    document.body.appendChild(script);

    // Clean up on unmount
    return () => {
      if (sdkRef.current) {
        sdkRef.current.remove();
      }
    };
  }, []);

  return (
    <div>
      <div className="dynamic-ad-container">
        <dynamic-ad ad-id="your-ad-id"></dynamic-ad>
      </div>
      <div className="dynamic-agent-container">
        <dynamic-agent agent-id="your-agent-id"></dynamic-agent>
      </div>
    </div>
  );
}

Node.js SDK Installation

Install the DynamicAds Node.js SDK:

# Using npm
npm install @dynamicads/sdk

# Or using yarn
yarn add @dynamicads/sdk

Node.js SDK Usage

Initialize and use the SDK:

import DynamicAdsClient from '@dynamicads/sdk';

// Initialize the client
const dynamicAds = new DynamicAdsClient({
  apiKey: process.env.DYNAMICADS_API_KEY
});

// Generate an ad
async function generateAd() {
  try {
    const { id } = await dynamicAds.generate({
      prompt: 'Create a dynamic product showcase',
      mediaType: 'video',
      dimensions: { width: 672, height: 384 }
    });

    // Wait for completion
    const ad = await dynamicAds.waitForCompletion(id);
    console.log('Generated ad:', ad);

    return ad;
  } catch (error) {
    console.error('Error:', error.message);
    throw error;
  }
}

import { DynamicAdsError, DynamicAdsTimeoutError } from '@dynamicads/sdk';

try {
  const ad = await dynamicAds.generate({
    prompt: 'Create an ad'
  });
  const completed = await dynamicAds.waitForCompletion(ad.id);
} catch (error) {
  if (error instanceof DynamicAdsTimeoutError) {
    console.error('Generation timed out');
  } else if (error instanceof DynamicAdsError) {
    console.error('API error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}