WaveSpeed API Setup

Connect WaveSpeed to unlock additional AI video models in Cuppa, starting with Higgsfield Director-of-Photography (DoP) image-to-video. WaveSpeed is an aggregator that hosts hundreds of third-party models behind a single, fast API.

What is WaveSpeed?

WaveSpeed AI is a unified API for running 700+ open and proprietary AI models - image, video, and audio. Cuppa uses WaveSpeed as the gateway to Higgsfield DoP, a video model that turns a still image into a cinematic 5-second clip with director-style camera moves (orbit, dolly, parallax push, vertigo zoom, anamorphic flare).

You bring your own WaveSpeed API key - Cuppa adds zero markup on generation costs.

What You Get

Wan 2.7 uses text-to-video by default; pass start_image_url to switch to image-to-video (optional end_image_url for start/end frame control).

Plan Availability

Video generation requires a Studio or higher plan.

Legacy plans: Business, Agency, and Agency+ include the same access (mapped to Studio, Scale, and Enterprise).

Step 1: Create a WaveSpeed Account

1. Go to wavespeed.ai
2. Click Sign up
3. Sign in with Google, GitHub, or email

Step 2: Get Your API Key

1. Go to wavespeed.ai/accesskey
2. Click Create new key
3. Name it “Cuppa”
4. Copy the key

Your key looks like: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 3: Add Billing

WaveSpeed bills per generation. Higgsfield DoP runs roughly $0.10–$0.30 per 5-second clip depending on settings.

1. Go to wavespeed.ai/billing
2. Add a payment method or top up credits

Step 4: Add the Key to Cuppa

1. Go to Team Settings → API Keys
2. Find the WaveSpeed section
3. Paste your API key
4. Click Save - Cuppa pings WaveSpeed to validate the key immediately

You can store multiple keys (e.g. one per client). Cuppa picks the right key automatically based on the model you choose.

Generating Videos with Higgsfield DoP

In the Web App

1. Go to Creative Studio → Video Generation
2. Open the model selector (bottom-left of the prompt area)
3. Pick Higgsfield DoP (via WaveSpeed)
4. Drop in or pick a Start Image from your Media Library - DoP is image-to-video, so this is required
5. (Optional) Pick an End Image to lock in a transition
6. Write a director-style prompt (see prompt tips below)
7. Hit Generate - typical render is 1–3 minutes

Via the CLI

cuppa video create 
  --prompt "Slow vertigo zoom revealing the city skyline behind, anamorphic flare" 
  --model wavespeed:higgsfield-dop-i2v 
  --start-image-url "https://your-cdn.com/hero.jpg" 
  --duration 5 
  --aspect-ratio 16:9

Then poll status:

cuppa video status <video-id>

Via MCP (Claude / ChatGPT / Cursor)

Tell your agent:

Use create_video with model: "wavespeed:higgsfield-dop-i2v", start_image_url: "https://…", prompt: "Orbit camera around the subject, soft volumetric light", then poll get_video_status until complete.

Via REST API

curl -X POST https://app.cuppa.ai/v1/video 
  -H "Authorization: Bearer $CUPPA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "wavespeed:higgsfield-dop-i2v",
    "prompt": "Anamorphic dolly-in on the steaming espresso, warm golden hour lighting",
    "start_image_url": "https://your-cdn.com/hero.jpg",
    "duration_seconds": 5,
    "aspect_ratio": "16:9"
  }'

Writing Good Higgsfield DoP Prompts

DoP is camera-led, not scene-led. Your image is the subject - your prompt is the director.

Structure

[Camera move] + [Subject focus] + [Lighting/mood] + [Optional environmental motion]

What works

• Camera verbs: orbit, dolly in/out, pull back, arc left/right, parallax push, vertigo zoom, crane up/down
• Lens language: anamorphic flare, shallow depth of field, soft volumetric light
• Subtle environmental motion: drifting steam, swaying foliage, golden-hour shimmer, light shifts

Examples

Product shot → cinematic ad:

Slow dolly-in on the bottle, warm cinematic golden hour, subtle steam drifting upward

Portrait → editorial reveal:

Slow orbit around the subject, soft volumetric light from the left, shallow depth of field

Landscape → trailer beat:

Vertigo zoom revealing the mountain range behind, slow drifting clouds, anamorphic flare on the sun

What to avoid

• No multiple shots - DoP is one continuous camera move
• No dialogue or sound effects - DoP is silent
• No scene changes - the still is your subject
• No technical render terms (“4k 60fps blender octane”) - describe what the camera and world should do

Brand DNA Integration

When you have Brand DNA configured for the selected site, Cuppa automatically enriches your prompt with brand colors and visual style - exactly the same way it does for Replicate models. Your prompt stays clean while the generated video reflects your brand.

Troubleshooting

”WaveSpeed API key required for this video model”

Add a WaveSpeed key in Team Settings → API Keys. Make sure the key is active (validation runs at save time).

”Higgsfield DoP requires a start image”

DoP is image-to-video only. Pick an image from your Media Library or paste a public URL into the Start Image field.

Video stuck on “Creating your video…”

Higgsfield DoP usually completes in 1–3 minutes. If it’s stuck beyond 10 minutes, the job will auto-fail. Check that:

• Your WaveSpeed key has billing/credit
• Your start image URL is publicly reachable (not behind auth)
• The image isn’t blocked by content moderation (try a different shot)

“Failed” generation

Click Edit & Retry in the gallery to try again. Common fixes:

• Simplify the prompt - DoP responds best to one camera move per generation
• Try a different start image (clean composition, clear subject works best)
• Switch aspect ratio if the original image’s framing doesn’t fit

Where do my generated videos live?

Same place as every other model. Generated videos appear in:

• Creative Studio → Video Generation gallery
• Media Library (filter to Videos)

WaveSpeed keeps the source video for 7 days, but Cuppa downloads and re-hosts it on your account immediately, so you keep the file forever.

Cost Reference

WaveSpeed bills per generation. Approximate per-clip cost for Higgsfield DoP at 5s / 720p is $0.10–$0.30. Check wavespeed.ai/pricing for current rates.

Cuppa adds zero markup - you pay WaveSpeed directly via your API key.

Related Docs

• Video Generation: Full overview of all video models
• Replicate API Setup: For Runway, Seedance, Kling, Veo, Grok, P-Video
• Brand Asset Library: Source images to use as DoP start frames
• Brand DNA: Lock in colors and style across every generation