# Higgsfield Video Models

# Higgsfield Video Generation API Guide

## Overview

Higgsfield provides several video-generation workflows, including basic image-to-video, talking-avatar video, and ad-video generation. This page explains when to use each endpoint.

## Endpoint Scenarios

### 1. Basic Image-to-Video - /higgsfield/generate

**Applicable scenarios**

- turn a static image into a dynamic video
- create short-form video content
- produce animation effects
- make social-media clips

**When to use**

- you already have a static image and want to add motion
- you need looping animation
- you want a product showcase clip
- you are creating artistic motion work

**Not suitable for**

- talking-head videos
- commercial ad videos with specialized ad effects

### 2. Talking Video - /higgsfield/speak

**Applicable scenarios**

- digital-human talking videos
- training and education content
- customer-service videos
- personal vlog-style material

**When to use**

- a person needs to speak on screen
- you are making an instructional video
- you need an automated customer-service reply video
- you are producing virtual-host content
- you already have audio and need lip-sync

**Audio source options**

- upload an audio file: when you already have a recorded wav/mp3 file
- text-to-speech: when you need to generate speech from text and choose a voice or sound style

### 3. Ad Video - /higgsfield/ads

**Applicable scenarios**

- product ads
- e-commerce promotion videos
- brand promotion
- marketing campaigns

**When to use**

- the product needs a polished advertising effect
- you are promoting goods on an e-commerce platform
- you are preparing a brand campaign
- you need specialized product-motion effects

**Notes**

- the cost is higher than the base workflow
- templates need to be obtained from the official site
- the endpoint is optimized specifically for commercial ad scenarios

## Standard Workflows

### Plan A: Basic Image-to-Video

1. Prepare the image
2. Get the motion-template list
3. Choose a suitable motion_id
4. Call the generation endpoint
5. Query task status
6. Get the video URL after completion

### Plan B: Talking Video

1. Prepare the character image
2. Get avatar presets
3. Decide the audio source
4. Upload an audio URL or configure text-to-speech
5. Optionally choose voice and sound presets
6. Configure the speak parameters
7. Call the speaking endpoint
8. Query task status
9. Get the video URL

### Plan C: Ad Video

1. Prepare the product image
2. Visit the official site to get ad templates
3. Choose product_placement_sample_id
4. Call the ads endpoint
5. Query task status
6. Get the video URL

## Cost Guidance

| Capability | Relative cost | Recommended use |
| --- | --- | --- |
| Basic video (lite) | 1x | testing and simple animation |
| Basic video (standard) | 2x | production content and higher quality |
| Basic video (turbo) | 1.4x | fast turnaround |
| Talking video | 10x | important speaking-avatar videos |
| Ad video | 2.6x | commercial promotion |

## Template Strategy

### 1. Motion Templates

~~~text
GET {{BASE_URL}}/higgsfield/tpl/motions?size=30&search=keyword
~~~

- browse available templates first
- search based on the motion effect you want
- record the target motion_id

### 2. Avatar Templates

~~~text
GET {{BASE_URL}}/higgsfield/tpl/avatar-presets?size=30
~~~

- choose a suitable on-screen persona
- consider the preference of the target audience
- record the avatar_preset_id

### 3. Voice and Sound Templates

~~~text
GET {{BASE_URL}}/higgsfield/tpl/voices
GET {{BASE_URL}}/higgsfield/tpl/sounds
~~~

- choose a suitable voice style
- add sound effects where needed

## Quick Decision Guide

| Goal | Recommended endpoint | Key parameter |
| --- | --- | --- |
| make an image move | /generate | motion_id |
| make a person speak | /speak | avatar_preset_id + audio / speak config |
| make a product ad | /ads | product_placement_sample_id |
| test quickly | /generate with lite | model: "lite" |
| highest output quality | /generate with standard | model: "standard" |
| urgent project | /generate with turbo | model: "turbo" |

## Troubleshooting

**How do I choose the right model?**

- lite: lowest cost, good for testing and previews
- standard: best for formal published output
- turbo: good when time is tight but quality still matters

**When should I upload audio versus use text-to-speech for talking videos?**

- upload audio if you already have a recorded file
- use text-to-speech if you want fast generation from text
- choose a specific voice_id if you need a certain speaking style