generate-pinterest-vertical-videos

Imported from rondoflow/rondoflow (packages/catalog/content/skills/generate-pinterest-vertical-videos/SKILL.md). Install upstream with npx skills add rondoflow/rondoflow --skill generate-pinterest-vertical-videos. Copyright stays with the author.

JSON2Video Pinterest Skill

Generate vertical videos (1080x1920) optimized for Pinterest using the JSON2Video API.

Prerequisites

1. JSON2Video API Key: Sign up at https://json2video.com/get-api-key/
2. Set Environment Variable:

   export JSON2VIDEO_API_KEY="your_api_key_here"

Quick Start

Create a video using a JSON configuration file:

python3 scripts/generate_video.py --config my-video.json --wait

Configuration Format

The video is defined as an array of scenes. Each scene contains:

Image Configuration

AI-Generated Image:

{
  "image": {
    "source": "ai",
    "ai_provider": "flux-schnell",
    "ai_prompt": "A minimalist workspace with laptop..."
  }
}

Available AI Providers:

• flux-pro - Highest quality, realistic images
• flux-schnell - Fast generation, good quality
• freepik-classic - Digital artwork style

URL-Based Image:

{
  "image": {
    "source": "https://example.com/image.jpg"
  }
}

Voice Configuration

AI-Generated Voice (TTS):

{
  "voice": {
    "source": "generated",
    "text": "Your voiceover text here",
    "voice_id": "en-US-EmmaMultilingualNeural",
    "model": "azure"
  }
}

Provided Audio File:

{
  "voice": {
    "source": "https://example.com/voiceover.mp3"
  }
}

Note on Scene Duration: The voiceover determines scene length automatically. Each scene's duration matches its audio length. For provided audio files, ensure they match your intended scene timing.

Complete Example

{
  "resolution": "instagram-story",
  "quality": "high",
  "cache": true,
  "scenes": [
    {
      "image": {
        "source": "ai",
        "ai_provider": "flux-schnell",
        "ai_prompt": "Affiliate marketing workspace with laptop and coffee"
      },
      "voice": {
        "source": "generated",
        "text": "Here's how to make money with affiliate marketing",
        "voice_id": "en-US-Neural2-F"
      },
      "text_overlay": "Affiliate Marketing 101",
      "subtitles": true,
      "zoom_effect": true
    }
  ]
}

Advanced: Split Long Voiceover into Scenes

For long scripts, split into multiple scenes with shorter voice segments:

{
  "scenes": [
    {
      "image": { "source": "ai", "ai_prompt": "Hook image" },
      "voice": { "source": "generated", "text": "Attention-grabbing hook..." },
      "zoom_effect": true
    },
    {
      "image": { "source": "ai", "ai_prompt": "Step 1 image" },
      "voice": { "source": "generated", "text": "Step one is to..." },
      "zoom_effect": true
    },
    {
      "image": { "source": "ai", "ai_prompt": "CTA image" },
      "voice": { "source": "generated", "text": "Click the link in bio..." },
      "zoom_effect": false
    }
  ]
}

Command Reference

Create video from config:

python3 scripts/generate_video.py --config video.json --wait

Create without waiting:

python3 scripts/generate_video.py --config video.json --no-wait

Check status of existing project:

python3 scripts/generate_video.py --project-id YOUR_PROJECT_ID

Resolution Options

Voice Models & IDs

Azure (Default - FREE, no credits consumed)

Voice format: en-US-EmmaMultilingualNeural

Common Azure voices:

• en-US-EmmaMultilingualNeural - Female, natural (recommended)
• en-US-GuyNeural - Male, professional
• en-US-JennyNeural - Female, friendly
• en-GB-SoniaNeural - British female
• en-GB-RyanNeural - British male

See Microsoft Azure Speech Voices for full list.

ElevenLabs (Premium - consumes credits)

Voice names: Natural names like Bella, Antoni, Nova, Shimmer

Available voices: Daniel, Serena, Antoni, Bella, Nova, Shimmer, and more.

See ElevenLabs Voice Library for full list.

Security

• API Key is NEVER stored in skill files
• API key must be set as environment variable JSON2VIDEO_API_KEY
• Script validates key exists before any API calls

Example Files

• scripts/example-config.json - Basic example with one scene
• scripts/example-advanced.json - Multi-scene affiliate marketing video

Advanced Usage

See ADVANCED.md for:

• Multi-scene video architecture patterns
• Image source strategies (AI vs URL vs hybrid)
• Voiceover patterns and best practices
• Subtitle styling options
• Pinterest-specific content tips
• Batch processing workflows
• Credit consumption optimization

Troubleshooting

Error: "JSON2VIDEO_API_KEY environment variable not set" → Run: export JSON2VIDEO_API_KEY="your_key"

Error: "Render failed" → Check: Image URLs are publicly accessible → Check: AI prompts don't violate content policies → Check: Audio files are valid MP3/WAV

Video takes too long → Enable cache: true in config → Use flux-schnell instead of flux-pro for faster generation → Pre-generate AI images and use URLs instead

Python API Usage

For programmatic use in other scripts:

from scripts.generate_video import create_pinterest_video

scenes = [
    {
        "image": {"source": "ai", "ai_prompt": "..."},
        "voice": {"source": "generated", "text": "..."},
        "subtitles": True,
        "zoom_effect": True
    }
]

video_url = create_pinterest_video(scenes, wait=True)
print(f"Video ready: {video_url}")