POST
/
higgsfield
/
speak
Speak
curl --request POST \
  --url https://api.unifically.com/higgsfield/speak \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image_url": "<string>",
  "audio_url": "<string>",
  "audio_task_id": "<string>",
  "prompt": "<string>",
  "quality": "<string>",
  "enhance_prompt": true,
  "seed": 123
}
'
{
  "code": 200,
  "data": {
    "task_id": "b7c92fe0-33c6-53fd-c975-566gc253f758",
    "error": {}
  }
}
Generate talking avatar videos by combining an image with audio (either from a custom URL or a completed TTS task).

​
Pricing

For current pricing, see the Pricing page.

​
Authentication

All endpoints require authentication using Bearer token authorization: 
-H 'Authorization: Bearer YOUR_API_KEY'

​
Request

​
With Audio URL

curl -X POST 'https://api.unifically.com/higgsfield/speak' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "https://example.com/person.jpg",
    "audio_url": "https://example.com/speech.wav",
    "prompt": "A person speaking with natural expressions",
    "quality": "basic"
  }'

​
With TTS Task ID

curl -X POST 'https://api.unifically.com/higgsfield/speak' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "https://example.com/person.jpg",
    "audio_task_id": "8e93f884-31d1-478d-92f6-ffc7ff1e868f",
    "prompt": "A person speaking with natural expressions",
    "quality": "high"
  }'

​
Parameters

​
image_url
string
required
URL of the person/avatar image
​
audio_url
string
Direct URL to audio file
​
audio_task_id
string
Task ID from a completed TTS job
​
prompt
string
required
Text description for the video generation
​
quality
string
Generation qualityOptions: "basic", "high"Default: "basic"
​
enhance_prompt
boolean
Whether to enhance/improve the prompt automaticallyDefault: true
​
seed
integer
Random seed for reproducible generation

​
Important Notes

  • You must provide either audio_url OR audio_task_id, but not both
  • When using audio_task_id, the system automatically validates that the task is a text2speech type and fetches the completed audio

​
Response

{
  "code": 200,
  "data": {
    "task_id": "b7c92fe0-33c6-53fd-c975-566gc253f758",
    "error": {}
  }
}

​
Response Fields

​
code
integer
default:"200"
HTTP status code (200 for success)
​
data
object
Response data
​
task_id
string
Unique identifier for this generation task
​
error
object
Error information (empty object for successful requests)

​
Error Responses

​
Invalid TTS Task Type:

{
  "code": 400,
  "data": {
    "message": "Task 8e93f884-31d1-478d-92f6-ffc7ff1e868f is not a TTS job. Please provide a valid TTS task ID.",
    "error": {}
  }
}

​
TTS Task Not Completed:

{
  "code": 400,
  "data": {
    "message": "TTS job is not completed yet (status: processing)",
    "error": {}
  }
}

​
Invalid Quality:

{
  "code": 400,
  "data": {
    "message": "quality must be either \"high\" or \"basic\"",
    "error": {}
  }
}
Use the task_id to check the status using the Get Task endpoint.