Getting Started

Get up and running with the Sketchpen API in under 5 minutes.

Prerequisites

A Sketchpen account (sign up)
An API key from your dashboard (Settings → API Keys)

Step 1: Make Your First API Call

Create a video using a text prompt:

bash

curl -X POST https://api.sketchpen.app/api/v1/videos \
  -H "X-Api-Key: sk_live_xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over the ocean with waves crashing",
    "aspect_ratio": "16:9"
  }'

Response:

json

{
  "id": "video_uuid",
  "status": "scripting",
  "prompt": "A beautiful sunset over the ocean with waves crashing",
  "theme": "presentation",
  "scenes": [],
  "video_url": null,
  "audio_url": null,
  "created_at": "2024-01-01T00:00:00Z"
}

⚠️ Credits

Creating a video requires at least 1 credit. Each scene costs 1 credit. See Credit Costs for details.

ℹ️ Timing

Script generation typically takes 10-30 seconds. The scenes array populates once the script is ready (status changes to refining).

Step 2: Poll for Script Generation

The AI generates the script in the background. Poll until scenes appear:

bash

curl https://api.sketchpen.app/api/v1/videos/{video_id} \
  -H "X-Api-Key: sk_live_xyz..."

When the script is ready, status changes to refining and scenes populates:

json

{
  "id": "video_uuid",
  "status": "refining",
  "scenes": [
    {
      "id": "scene_uuid",
      "speech": "Welcome to our stunning sunset scene...",
      "visual_description": "A golden sunset over calm ocean waves",
      "image_url": null,
      "captions": []
    }
  ],
  "created_at": "2024-01-01T00:00:00Z"
}

Step 3: Approve and Generate

Once you're happy with the script, approve it to start video generation:

bash

curl -X POST https://api.sketchpen.app/api/v1/videos/{video_id}/approve \
  -H "X-Api-Key: sk_live_xyz..."

This triggers image generation, audio narration, and video rendering. The status changes to visualising.

ℹ️ Timing

Full video generation (approve → completed) typically takes 1-5 minutes depending on scene count. Longer videos take more time.

Step 4: Wait for Completion

Poll until the video is ready:

bash

curl https://api.sketchpen.app/api/v1/videos/{video_id} \
  -H "X-Api-Key: sk_live_xyz..."

When complete:

json

{
  "id": "video_uuid",
  "status": "completed",
  "scenes": [
    {
      "id": "scene_uuid",
      "speech": "Welcome to our stunning sunset scene...",
      "visual_description": "A golden sunset over calm ocean waves",
      "image_url": null,
      "captions": [
        {"word": "Welcome", "start": 0.0, "end": 0.4},
        {"word": "to", "start": 0.4, "end": 0.5}
      ]
    }
  ],
  "video_url": "https://bucket.s3.region.amazonaws.com/key?X-Amz-Algorithm=...",
  "thumbnail_url": "https://bucket.s3.region.amazonaws.com/key?X-Amz-Algorithm=..."
}

ℹ️ Presigned URLs

video_url and thumbnail_url are presigned S3 URLs that expire after 7 days. Download files you want to keep permanently.

Complete Example

Here's a runnable bash script that creates a video, waits for completion, and downloads it:

bash

#!/bin/bash
API_KEY="sk_live_your_key_here"
BASE="https://api.sketchpen.app/api/v1"

# 1. Create video
VIDEO_ID=$(curl -s -X POST "$BASE/videos" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A beautiful sunset over the ocean"}' | jq -r '.id')
echo "Created: $VIDEO_ID"

# 2. Poll for script, then approve
while true; do
  STATUS=$(curl -s "$BASE/videos/$VIDEO_ID" -H "X-Api-Key: $API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  [[ "$STATUS" == "refining" ]] && break
  [[ "$STATUS" == "failed" ]] && echo "Script failed!" && exit 1
  sleep 5
done

curl -s -X POST "$BASE/videos/$VIDEO_ID/approve" -H "X-Api-Key: $API_KEY"
echo "Approved - generating video..."

# 3. Poll for completion, then download
while true; do
  RESP=$(curl -s "$BASE/videos/$VIDEO_ID" -H "X-Api-Key: $API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status')
  [[ "$STATUS" == "completed" ]] && break
  [[ "$STATUS" == "failed" ]] && echo "Video failed!" && exit 1
  echo "Status: $STATUS"
  sleep 10
done

VIDEO_URL=$(echo "$RESP" | jq -r '.video_url')
curl -o video.mp4 "$VIDEO_URL"
echo "Downloaded video.mp4"

Video Status Lifecycle

Videos progress through these statuses:

pending - Video created, processing not started
scripting - AI is generating the script
refining - Script is ready for review
visualising - Generating visual scenes
narrating - Generating audio voiceovers
curating - Synchronizing assets
rendering - Rendering final video
completed - Video ready
failed - Generation failed (see Troubleshooting)

Next Steps

Videos API - Full video endpoint reference
Webhooks - Get notified when videos are ready
Assets - Upload custom speakers and images
Themes & Config - Customize video appearance