ClipyardAPI Documentation
OverviewAuthenticationUsage & LimitsAPI EndpointsGet AccountList VoicesGenerate VideoVideo StatusWebhooksError HandlingCode Examples

API Documentation

Complete guide to using the Clipyard API for video generation.

Base URL

https://clipyard.ai/api/external/v1

The Clipyard API uses an asynchronous request-response pattern. When you submit a video generation request, it enters a queue and processes in the background. This approach offers several advantages:

  • Monitor task status without maintaining open connections
  • Handle long-running video generation tasks efficiently
  • Receive webhook notifications when videos are ready
  • Integrate easily with automation platforms like n8n, Zapier, and Make

Authentication

All API requests require authentication using an API key. You can create and manage API keys in your dashboard settings.

Include your API key in the Authorization header:

curl -H "Authorization: Bearer rg_live_your_api_key_here" \
  https://clipyard.ai/api/external/v1/account

Important: Keep your API keys secure. Never expose them in client-side code or public repositories. If a key is compromised, revoke it immediately in your dashboard.

Usage & Limits

API usage counts towards your existing subscription quota. Each video or image generated via the API is deducted from your plan's monthly allowance, just like generations made through the dashboard.

Video Generation

Each video created via the API uses 1 video credit from your plan.

Image Generation

Each image created via the API uses 1 image credit from your plan.

Check your current usage and remaining limits via the /account endpoint.

API Endpoints

The following endpoints are available for interacting with the Clipyard API.

GET

/account

Retrieve your account information, subscription details, and current usage limits.

Request

curl -X GET "https://clipyard.ai/api/external/v1/account" \
  -H "Authorization: Bearer rg_live_your_api_key"

Response

{
  "user_id": "uuid-here",
  "api_key": {
    "id": "key-uuid",
    "name": "My API Key",
    "is_platform_key": false
  },
  "subscription": {
    "plan": "pro",
    "status": "active"
  },
  "usage": {
    "videos": {
      "used": 5,
      "limit": 50,
      "remaining": 45
    },
    "images": {
      "used": 10,
      "limit": 100,
      "remaining": 90
    },
    "avatar_credits": {
      "total": 10,
      "used": 2,
      "remaining": 8
    }
  }
}
GET

/voices

List all available text-to-speech voices for video narration.

Request

curl -X GET "https://clipyard.ai/api/external/v1/voices" \
  -H "Authorization: Bearer rg_live_your_api_key"

Response

{
  "voices": [
    {
      "id": "voice_id_here",
      "name": "Rachel",
      "provider": "elevenlabs",
      "category": "premade",
      "language": "en",
      "gender": "female",
      "age": "young",
      "description": "Clear and professional",
      "preview_url": "https://..."
    }
  ],
  "total": 50
}
POST

/videos/generate

Submit a new video generation request. The video will be processed asynchronously.

Request Body

ParameterTypeRequiredDescription
scriptstringRequiredThe narration script (max 10,000 characters)
voice_idstringOptionalVoice ID from /voices endpoint
voice_settingsobjectOptionalVoice parameters (stability, speed, etc.)
visual_stylestringOptional"ai_generated" or "avatar"
visual_promptstringOptionalPrompt for AI-generated visuals
avatar_urlstringOptionalURL of avatar image (if visual_style is "avatar")
aspect_ratiostringOptional"16:9", "9:16", or "1:1" (default: "9:16")
subtitlesobjectOptionalSubtitle configuration
webhook_urlstringOptionalURL to receive completion webhook
metadataobjectOptionalCustom metadata returned in webhook

Voice Settings Object

ParameterTypeRequiredDescription
stabilitynumberOptionalVoice stability (0-1)
similarity_boostnumberOptionalVoice similarity (0-1)
stylenumberOptionalVoice style exaggeration (0-1)
speednumberOptionalSpeaking speed multiplier

Subtitles Object

ParameterTypeRequiredDescription
enabledbooleanOptionalEnable subtitles (default: true)
stylestringOptionalSubtitle style preset
fontstringOptionalFont family (default: "Montserrat")
colorstringOptionalText color hex (default: "#FFFFFF")
positionstringOptional"top", "center", or "bottom"

Example Request

curl -X POST "https://clipyard.ai/api/external/v1/videos/generate" \
  -H "Authorization: Bearer rg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Welcome to our product demo. Today we will show you...",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "visual_style": "ai_generated",
    "visual_prompt": "Professional tech product showcase",
    "aspect_ratio": "9:16",
    "subtitles": {
      "enabled": true,
      "position": "bottom",
      "color": "#FFFFFF"
    },
    "webhook_url": "https://your-server.com/webhooks/clipyard",
    "metadata": {
      "campaign_id": "summer-2024",
      "internal_ref": "video-001"
    }
  }'

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "estimated_duration_seconds": 45,
  "webhook_registered": true,
  "created_at": "2024-01-20T12:00:00Z"
}
GET

/videos/:id

Check the status and retrieve the result of a video generation job.

Path Parameters

ParameterTypeRequiredDescription
iduuidRequiredThe job_id returned from /videos/generate

Request

curl -X GET "https://clipyard.ai/api/external/v1/videos/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer rg_live_your_api_key"

Response (Pending/Processing)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "type": "VIDEO",
  "progress": 50,
  "created_at": "2024-01-20T12:00:00Z",
  "started_at": "2024-01-20T12:00:05Z"
}

Response (Completed)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "type": "VIDEO",
  "progress": 100,
  "result": {
    "video_url": "https://cdn.clipyard.ai/videos/...",
    "thumbnail_url": "https://cdn.clipyard.ai/thumbnails/...",
    "duration_seconds": 45,
    "file_size_bytes": 15728640
  },
  "created_at": "2024-01-20T12:00:00Z",
  "completed_at": "2024-01-20T12:02:30Z",
  "metadata": {
    "campaign_id": "summer-2024",
    "internal_ref": "video-001"
  }
}

Job Statuses

StatusDescription
pendingJob is queued and waiting to start
processingJob is currently being processed
completedJob finished successfully, video is ready
failedJob failed, check error field for details

Webhooks

If you provide a webhook_url when generating a video, we'll send a POST request to that URL when the job completes.

Webhook Payload

{
  "event": "video.completed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "video_url": "https://cdn.clipyard.ai/videos/...",
    "thumbnail_url": "https://cdn.clipyard.ai/thumbnails/...",
    "duration_seconds": 45,
    "file_size_bytes": 15728640
  },
  "metadata": {
    "campaign_id": "summer-2024",
    "internal_ref": "video-001"
  },
  "timestamp": "2024-01-20T12:02:30Z"
}

Failed Job Webhook

{
  "event": "video.failed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Script contains unsupported characters",
  "metadata": {
    "campaign_id": "summer-2024",
    "internal_ref": "video-001"
  },
  "timestamp": "2024-01-20T12:01:00Z"
}

Tip: Your webhook endpoint should respond with a 2xx status code within 30 seconds. If we don't receive a response, we'll retry up to 3 times with exponential backoff.

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
404Not Found - Resource doesn't exist
429Rate Limited - Too many requests or usage limit reached
500Internal Server Error

Error Response Format

{
  "error": "Description of what went wrong"
}

Code Examples

Python

import requests
import time

API_KEY = "rg_live_your_api_key"
BASE_URL = "https://clipyard.ai/api/external/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Generate a video
response = requests.post(f"{BASE_URL}/videos/generate", headers=headers, json={
    "script": "Welcome to our product demo...",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "visual_style": "ai_generated",
    "aspect_ratio": "9:16"
})

job = response.json()
job_id = job["job_id"]
print(f"Job created: {job_id}")

# Poll for completion
while True:
    status_response = requests.get(f"{BASE_URL}/videos/{job_id}", headers=headers)
    status = status_response.json()

    if status["status"] == "completed":
        print(f"Video ready: {status['result']['video_url']}")
        break
    elif status["status"] == "failed":
        print(f"Job failed: {status.get('error')}")
        break

    print(f"Progress: {status.get('progress', 0)}%")
    time.sleep(5)

JavaScript (Node.js)

const API_KEY = 'rg_live_your_api_key';
const BASE_URL = 'https://clipyard.ai/api/external/v1';

async function generateVideo() {
  // Generate a video
  const response = await fetch(`${BASE_URL}/videos/generate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      script: 'Welcome to our product demo...',
      voice_id: 'EXAVITQu4vr4xnSDxMaL',
      visual_style: 'ai_generated',
      aspect_ratio: '9:16'
    })
  });

  const job = await response.json();
  console.log('Job created:', job.job_id);

  // Poll for completion
  while (true) {
    const statusResponse = await fetch(`${BASE_URL}/videos/${job.job_id}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });
    const status = await statusResponse.json();

    if (status.status === 'completed') {
      console.log('Video ready:', status.result.video_url);
      break;
    } else if (status.status === 'failed') {
      console.log('Job failed:', status.error);
      break;
    }

    console.log('Progress:', status.progress + '%');
    await new Promise(r => setTimeout(r, 5000));
  }
}

generateVideo();

n8n HTTP Request Node

For n8n integration, use the HTTP Request node with these settings:

{
  "method": "POST",
  "url": "https://clipyard.ai/api/external/v1/videos/generate",
  "authentication": "genericCredentialType",
  "genericAuthType": "httpHeaderAuth",
  "headerAuth": {
    "name": "Authorization",
    "value": "Bearer {{ $credentials.apiKey }}"
  },
  "sendBody": true,
  "bodyContentType": "json",
  "body": {
    "script": "{{ $json.script }}",
    "voice_id": "{{ $json.voice_id }}",
    "webhook_url": "your-n8n-webhook-url"
  }
}

Need help? Contact us at support@clipyard.ai

Go to Dashboard