Video Endpoints

POST /api/v1/studio/video/generate

Generate a video from a text prompt. Supports text-to-video, image-to-video, and reference-guided generation depending on the model.

Request Body

promptstringrequired

Video description (1–4000 characters).

modelstringrequired

Model: veo, veo-fast, kling-3.0-std, kling-3.0-pro, kling-3.0-4k, wan-2.6, wan-2.7, seedance-2.0, grok-video, or grok-video-v1.5.

durationnumber

Duration in seconds (varies by model, default varies).

aspectRatiostring

Aspect ratio: 16:9, 9:16, or 1:1.

resolutionstring

Resolution: 480p, 720p, or 1080p.

imageUrlstring

Image URL for image-to-video generation.

referenceImageUrlstring

Reference image URL (Seedance only).

referenceImagesstring[]

Reference images for Kling 3.0 reference-to-video — up to 4 (std/pro) or 7 (4k). The first image is the start frame.

endImageUrlstring

End frame image URL (Kling 3.0 image-to-video and WAN 2.7 image-to-video).

sourceVideoUrlstring

Source video to transform (WAN 2.7 edit-video only).

audioUrlstring

Audio track to condition output on (WAN 2.7 only).

referenceVideosstring[]

Multi-video references — WAN 2.7 reference-to-video (≤3) and Seedance reference-to-video (token-mapped, ≤3).

negativePromptstring

Negative prompt to avoid certain elements.

generateAudioboolean

Generate audio along with the video.

cfgScalenumber

Classifier-free guidance scale (Kling only, 0–1, default 0.5).

shotTypestring

Kling 3.0 only — customize (default) or intelligent.

seednumber

Seed for reproducibility.

Models

Model	Provider	Features
veo	Google	Text-to-video, image-to-video, up to 8s
veo-fast	Google	Faster generation, lower quality
kling-3.0-std	Kuaishou	T2V, I2V, end-frame, audio, 3–15s
kling-3.0-pro	Kuaishou	T2V, I2V, end-frame, audio, 3–15s
kling-3.0-4k	Kuaishou	T2V, I2V, 4K output, end-frame, audio, 3–15s
wan-2.6	Alibaba	Text-to-video, image-to-video, up to 5s
wan-2.7	Alibaba	Text/image/reference/edit-video, 3–10s, 720p/1080p, optional audio track
seedance-2.0	ByteDance	Text-to-video, reference-guided, up to 10s
seedance-2.0-fast	ByteDance	Faster/cheaper Seedance, text/image/reference-to-video, up to 10s
pixverse-v6	Pixverse	Text-to-video, image-to-video, 5/8s, up to 1080p
grok-video	xAI	Text-to-video, up to 10s
grok-video-v1.5	xAI	Image-to-video only (requires imageUrl), 480p/720p, up to 10s

Example

curl

curl -X POST https://terramind.com/api/v1/studio/video/generate \
  -H "Authorization: Bearer sk-tm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A drone flying over a tropical island at sunset",
    "model": "veo",
    "duration": 5,
    "aspectRatio": "16:9"
  }'

Response

JSON

{
  "success": true,
  "data": {
    "url": "https://storage.googleapis.com/...",
    "storagePath": "studios/.../video.mp4",
    "format": "mp4",
    "duration": 5000,
    "model": "veo",
    "metadata": {
      "aspectRatio": "16:9",
      "enhancedPrompt": "A cinematic drone shot..."
    }
  },
  "credits": { "used": 1, "cost": 25.0, "remaining": 9975.0 }
}

POST /api/v1/studio/video/remove-background

Remove the background from a video using fal.ai VEED. Three variants: standard (best quality), fast (cheaper), and green-screen (replace the background with a solid color).

Request Body

videoUrlstringrequired

URL of the input video.

durationSecondsnumberrequired

Duration of the source video in seconds — used for billing.

variantstring

standard (default), fast, or green-screen.

backgroundColorstring

Hex/named color (green-screen only). Defaults to green.

persistToStorageboolean

Re-upload the result to Terramind storage (default true).

Example

curl

curl -X POST https://terramind.com/api/v1/studio/video/remove-background \
  -H "Authorization: Bearer sk-tm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://...mp4",
    "durationSeconds": 8,
    "variant": "standard"
  }'

POST /api/v1/studio/video/upscale

Upscale a video to a higher resolution using fal.ai Topaz. Optionally interpolate to a higher target frame rate for smoother motion.

Request Body

videoUrlstringrequired

URL of the input video.

durationSecondsnumberrequired

Duration of the source video in seconds — used for billing.

upscaleFactornumber

2 (default) or 4. 4x is significantly more expensive.

targetFpsnumber

Optional target frame rate: 24, 30, 48, or 60.

persistToStorageboolean

Re-upload the result to Terramind storage (default true).

Example

curl

curl -X POST https://terramind.com/api/v1/studio/video/upscale \
  -H "Authorization: Bearer sk-tm-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://...mp4",
    "durationSeconds": 8,
    "upscaleFactor": 2,
    "targetFps": 60
  }'

Billing & Credit Reservation

Video generations are expensive, so credits are reserved when the request is accepted and charged only after the video is successfully stored. Any failure along the way (fal provider error, missing output URL, download or upload failure) releases the reservation automatically and leaves your balance untouched. Webhook-driven deliveries settle the reservation exactly once per job. Insufficient balance returns 402 INSUFFICIENT_CREDITS; hitting the 6-hour usage window returns 429 WINDOW_EXHAUSTED with a resetAt timestamp. See Credit Reservation for details.