中文 | English

Flyworks (a.k.a. Hifly) AI Avatar API V2

This document is intended for third-party systems to integrate with AI avatar generation capabilities.

General

All interfaces use Bearer Token authentication. You need to include "Authorization":"Bearer ${token}" in the request header. You can obtain the API token Here.

If the token verification fails, a 401 status code will be returned. For other exceptions, a 200 status code will be returned, and the specific exception reason can be identified through the error code in the response body.

Interface List

Avatar Cloning

Create Avatar by Video

• Interface:

  POST /api/v2/hifly/avatar/create_by_video

• Request Parameters:

  Parameter	Type	Description
  title	string	Name, default "Untitled"
  video_url	url	Video URL address, choose one with file_id
  file_id	string	File ID, choose one with video_url

• Response Parameters:

  Parameter	Type	Description
  message	string	Error message on failure
  code	int	Error code on failure
  task_id	string	Task ID
  request_id	string	Request code

• Request Example:

Python Example:

import requests

url = "https://hfw-api.hifly.cc/api/v2/hifly/avatar/create_by_video"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
payload = {
    "title": "My Digital Human",
    "video_url": "https://example.com/my_video.mp4"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

cURL Example:

curl -X POST "https://hfw-api.hifly.cc/api/v2/hifly/avatar/create_by_video" \
   -H "Authorization: Bearer YOUR_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"title": "My Digital Human", "video_url": "https://example.com/my_video.mp4"}'

• Response Example:

{
  "code": 0,
  "message": "",
  "task_id": "1234567890123456",
  "request_id": "req123456789"
}

Create Avatar by Image

This interface will result in point consumption.

• Interface:

  POST /api/v2/hifly/avatar/create_by_image

• Request Parameters:

  Parameter	Type	Description
  title	string	Name, default "Untitled"
  image_url	url	Image URL address, choose one with file_id
  file_id	string	File ID, choose one with image_url
  model	int	Model type, 1: Video 2.0, 2: Video 2.1, default 2

• Response Parameters:

  Parameter	Type	Description
  message	string	Error message on failure
  code	int	Error code on failure
  task_id	string	Task ID
  request_id	string	Request code

• Request Example:

Python Example:

import requests

url = "https://hfw-api.hifly.cc/api/v2/hifly/avatar/create_by_image"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
payload = {
    "title": "My Image Avatar",
    "image_url": "https://example.com/my_image.jpg",
    "model": 2
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

cURL Example:

curl -X POST "https://hfw-api.hifly.cc/api/v2/hifly/avatar/create_by_image" \
   -H "Authorization: Bearer YOUR_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"title": "My Image Avatar", "image_url": "https://example.com/my_image.jpg", "model": 2}'

• Response Example:

{
  "code": 0,
  "message": "",
  "task_id": "1234567890123456",
  "request_id": "req123456789"
}

Query Task Status

• Interface:

  GET /api/v2/hifly/avatar/task

• Request Parameters:

  Parameter	Type	Description
  task_id	string	Task ID ,required

• Response Parameters:

  Parameter	Type	Description
  message	string	Error message on failure
  code	int	Error code on failure
  status	int	Status, 1: Waiting 2: Processing 3: Completed 4: Failed
  avatar	string	Digital human identifier
  request_id	string	Request code

• Request Example:

Python Example:

import requests

task_id = "1234567890123456"
url = f"https://hfw-api.hifly.cc/api/v2/hifly/avatar/task?task_id={task_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

cURL Example:

curl -X GET "https://hfw-api.hifly.cc/api/v2/hifly/avatar/task?task_id=1234567890123456" \
   -H "Authorization: Bearer YOUR_TOKEN"

• Response Example:

  {
    "code": 0,
    "message": "",
    "status": 3,
    "avatar": "av_abc123xyz",
    "request_id": "req123456789"
  }
  

Voice Cloning

Create Voice

• Interface Address

POST /api/v2/hifly/voice/create

• Request Parameters

• Response Parameters

• Request Example:

  Python Example:

  import requests
  
  url = "https://hfw-api.hifly.cc/api/v2/hifly/voice/create"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }
  payload = {
      "title": "My Voice",
      "voice_type": 8,
      "audio_url": "https://example.com/my_audio.mp3"
  }
  
  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  

  cURL Example:

  curl -X POST "https://hfw-api.hifly.cc/api/v2/hifly/voice/create" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"title": "My Voice", "voice_type": 8, "audio_url": "https://example.com/my_audio.mp3"}'
  

• Response Example:

  {
    "code": 0,
    "message": "",
    "task_id": "1234567890123456",
    "request_id": "req123456789"
  }
  

Edit Voice Parameters

• Interface Address

POST /api/v2/hifly/voice/edit

• Request Parameters

• Response Parameters

• Request Example:

  Python Example:

  import requests
  
  url = "https://hfw-api.hifly.cc/api/v2/hifly/voice/edit"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }
  payload = {
      "voice": "voice_abc123",
      "rate": "1.2",
      "volume": "1.0",
      "pitch": "0.9"
  }
  
  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  

  cURL Example:

  curl -X POST "https://hfw-api.hifly.cc/api/v2/hifly/voice/edit" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"voice": "voice_abc123", "rate": "1.2", "volume": "1.0", "pitch": "0.9"}'
  

• Response Example:

  {
    "code": 0,
    "message": "",
    "request_id": "req123456789"
  }
  

Query Voice List

Query completed cloned voices and public voices

• Interface Address

GET /api/v2/hifly/voice/list

• Request Parameters

• Response Parameters

• Request Example:

  Python Example:

  import requests
  
  url = "https://hfw-api.hifly.cc/api/v2/hifly/voice/list"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }
  params = {
      "page": 1,
      "size": 10,
      "kind": 1
  }
  
  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  

  cURL Example:

  curl -X GET "https://hfw-api.hifly.cc/api/v2/hifly/voice/list?page=1&size=10&kind=1" \
     -H "Authorization: Bearer YOUR_TOKEN"
  

• Response Example:

  {
    "code": 0,
    "message": "",
    "data": [
      {
        "voice": "voice_abc123",
        "type": 20,
        "title": "My Voice",
        "rate": "1.0",
        "volume": "1.0",
        "pitch": "1.0"
      },
      {
        "voice": "voice_def456",
        "type": 10,
        "title": "Public Voice 1",
        "rate": "1.0",
        "volume": "1.0",
        "pitch": "1.0"
      }
    ],
    "request_id": "req123456789"
  }
  

Query Task Status

• Interface:

  GET /api/v2/hifly/voice/task

• Request Parameters:

  Parameter	Type	Description
  task_id	string	Task ID

• Response Parameters:

  Parameter	Type	Description
  message	string	Error message on failure
  code	int	Error code on failure
  status	int	Status, 1: Waiting 2: Processing 3: Completed 4: Failed
  voice	string	Voice identifier
  demo_url	url	Demo voice file address
  request_id	string	Request code

• Request Example:

  Python Example:

  import requests
  
  task_id = "1234567890123456"
  url = f"https://hfw-api.hifly.cc/api/v2/hifly/voice/task?task_id={task_id}"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }
  
  response = requests.get(url, headers=headers)
  print(response.json())
  

  cURL Example:

  curl -X GET "https://hfw-api.hifly.cc/api/v2/hifly/voice/task?task_id=1234567890123456" \
     -H "Authorization: Bearer YOUR_TOKEN"
  

• Response Example:

  {
    "code": 0,
    "message": "",
    "status": 3,
    "voice": "voice_abc123",
    "demo_url": "https://example.com/demo_audio.mp3",
    "request_id": "req123456789"
  }
  

Creation

Video Creation (Audio Driven)

This interface will result in point consumption.

• Interface:

  POST /api/v2/hifly/video/create_by_audio

• Request Parameters

• Response Parameters:

• Request Example:

Python Example:

import requests

url = "https://hfw-api.hifly.cc/api/v2/hifly/video/create_by_audio"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
payload = {
    "title": "Audio Driven Video",
    "audio_url": "https://example.com/my_audio.mp3",
    "avatar": "av_abc123xyz",
    "pipeline": "1.5"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

cURL Example:

curl -X POST "https://hfw-api.hifly.cc/api/v2/hifly/video/create_by_audio" \
   -H "Authorization: Bearer YOUR_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"title": "Audio Driven Video", "audio_url": "https://example.com/my_audio.mp3", "avatar": "av_abc123xyz", "pipeline": "1.5"}'

• Response Example:

  {
    "code": 0,
    "message": "",
    "task_id": "1234567890123456",
    "request_id": "req123456789"
  }
  

Video Creation (Text Driven)

This interface will result in point consumption.

• Interface:

  POST /api/v2/hifly/video/create_by_tts

• Request Parameters:

• Response Parameters:

• Request Example:

Python Example:

import requests

url = "https://hfw-api.hifly.cc/api/v2/hifly/video/create_by_tts"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
payload = {
    "title": "Text Driven Video",
    "text": "This is a test text for generating digital human video.",
    "voice": "voice_abc123",
    "avatar": "av_abc123xyz",
    "pipeline": "1.5"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

cURL Example:

curl -X POST "https://hfw-api.hifly.cc/api/v2/hifly/video/create_by_tts" \
   -H "Authorization: Bearer YOUR_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"title": "Text Driven Video", "text": "This is a test text for generating digital human video.", "voice": "voice_abc123", "avatar": "av_abc123xyz", "pipeline": "1.5"}'

• Response Example:

  {
    "code": 0,
    "message": "",
    "task_id": "1234567890123456",
    "request_id": "req123456789"
  }
  

Audio Creation

This interface will result in point consumption.

• Interface:

  POST /api/v2/hifly/audio/create_by_tts

• Request Parameters:

• Response Parameters:

• Request Example:

Python Example:

import requests

url = "https://hfw-api.hifly.cc/api/v2/hifly/audio/create_by_tts"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
payload = {
    "title": "Audio Creation",
    "text": "This is a test text for generating audio.",
    "voice": "voice_abc123"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

cURL Example:

curl -X POST "https://hfw-api.hifly.cc/api/v2/hifly/audio/create_by_tts" \
   -H "Authorization: Bearer YOUR_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"title": "Audio Creation", "text": "This is a test text for generating audio.", "voice": "voice_abc123"}'

• Response Example:

  {
    "code": 0,
    "message": "",
    "task_id": "1234567890123456",
    "request_id": "req123456789"
  }
  

Query Creation Task Status

• Interface:

  GET /api/v2/hifly/video/task

• Request Parameters:

  Parameter	Type	Description
  task_id	string	Task ID

• Response Parameters:

  Parameter	Type	Description
  message	string	Error message on failure
  code	int	Error code on failure
  status	int	Work status, 1: Waiting 2: Processing 3: Completed 4: Failed
  video_Url	url	Synthesized video address. This is a temporary address, please save it as soon as possible. The URL will contain query parameters, please ensure compatibility when downloading the video.
  duration	int	Work duration, unit: seconds
  request_id	string	Request code

• Request Example:

  Python Example:

  import requests
  
  task_id = "1234567890123456"
  url = f"https://hfw-api.hifly.cc/api/v2/hifly/video/task?task_id={task_id}"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }
  
  response = requests.get(url, headers=headers)
  print(response.json())
  

  cURL Example:

  curl -X GET "https://hfw-api.hifly.cc/api/v2/hifly/video/task?task_id=1234567890123456" \
     -H "Authorization: Bearer YOUR_TOKEN"
  

• Response Example:

  {
    "code": 0,
    "message": "",
    "status": 3,
    "video_Url": "https://example.com/videos/abc123.mp4?token=xyz789",
    "duration": 45,
    "request_id": "req123456789"
  }
  

System

Message Callback

After the task is completed, the message will be actively pushed to the callback address.

If the response status code is not 200, it is considered a notification failure, and it will retry within 5 minutes, and will not retry thereafter.

You can set the callback address Here.

Digital Human Cloning Task

• Request Parameters

  Parameter	Type	Description
  message	string	Error message on failure
  code	int	Error code on failure
  type	int	Message type: 2 for digital human
  status	int	Status, 3: Completed 4: Failed
  avatar	string	Digital human identifier

• Response Example:

  {
    "message": "",
    "code": 0,
    "type": 2,
    "status": 3,
    "avatar": "av_abc123xyz"
  }
  

Voice Cloning Task

• Request Parameters

  Parameter	Type	Description
  message	string	Error message on failure
  code	int	Error code on failure
  type	int	Message type: 3 for voice
  status	int	Status, 3: Completed 4: Failed
  voice	string	Voice identifier
  demo_url	url	Demo voice file address

• Response Example:

  {
    "message": "",
    "code": 0,
    "type": 3,
    "status": 3,
    "voice": "voice_abc123",
    "demo_url": "https://example.com/demo_audio.mp3"
  }
  

Creation Task

• Request Parameters

  Parameter	Type	Description
  status	int	Work status, 3: Completed 4: Failed
  video_Url	url	Synthesized video address. This is a temporary address, please save it as soon as possible. The URL will contain query parameters, please ensure compatibility when downloading the video.
  type	int	Message type: 1 for work.
  duration	int	Work duration, unit: seconds
  message	string	Error message on failure
  code	int	Error code on failure
  title	string	Work name

• Response Example:

  {
    "status": 3,
    "video_Url": "https://example.com/videos/abc123.mp4?token=xyz789",
    "type": 1,
    "duration": 45,
    "message": "",
    "code": 0,
    "title": "My Video Creation"
  }
  

Upload File

First obtain the upload address, then upload the file

Obtain Upload Address

• Interface:

  POST /api/v2/hifly/tool/create_upload_url

• Request Parameters

  Parameter	Type	Description
  file_extension	string	Extension, such as mp4, mp3, etc.

• Response Parameters

  Parameter	Type	Description
  upload_url	string	Upload address
  content_type	string	File mime-type, needs to set Content-Type when uploading
  file_id	string	File ID
  request_id	string	Request code

• Request Example:

  Python Example:

  import requests
  
  url = "https://hfw-api.hifly.cc/api/v2/hifly/tool/create_upload_url"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }
  payload = {
      "file_extension": "mp4"
  }
  
  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  

  cURL Example:

  curl -X POST "https://hfw-api.hifly.cc/api/v2/hifly/tool/create_upload_url" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"file_extension": "mp4"}'
  

• Response Example:

  {
    "upload_url": "https://upload.hifly.cc/test%2Fa.mp4?Expires=1745576446&OSSAccessKeyId=LTAI5tPx2KRcdE3ihKTp5c36&Signature=rY86EuJEqzwYkOPnwOJDHPwP9Ew%3D",
    "content_type": "video/mp4",
    "file_id": "file_abc123xyz",
    "request_id": "req123456789"
  }
  

Upload File

• Description

  • Use PUT method to upload the file to upload_url
  • Use binary method to upload the file
  • Set Content-Type in the request header

• Example

  Python Example:

  import requests
  
  # Assuming we have obtained the upload address from the previous step
  upload_url = "https://upload.hifly.cc/test%2Fa.mp4?Expires=1745576446&OSSAccessKeyId=LTAI5tPx2KRcdE3ihKTp5c36&Signature=rY86EuJEqzwYkOPnwOJDHPwP9Ew%3D"
  content_type = "video/mp4"
  file_path = "/path/to/your/file.mp4"
  
  with open(file_path, 'rb') as file:
      headers = {
          "Content-Type": content_type
      }
      response = requests.put(upload_url, headers=headers, data=file)
      print(f"Status code: {response.status_code}")
  

  cURL Example:

  curl -i -X PUT -T ./my_video.mp4 \
     -H 'Content-Type: video/mp4' \
     'https://upload.hifly.cc/test%2Fa.mp4?Expires=1745576446&OSSAccessKeyId=LTAI5tPx2KRcdE3ihKTp5c36&Signature=rY86EuJEqzwYkOPnwOJDHPwP9Ew%3D'
  

Query Account Credits

• Interface Address

GET /api/v2/hifly/account/credit

• Request Parameters

None

• Response Parameters

• Request Example:

  Python Example:

  import requests
  
  url = "https://hfw-api.hifly.cc/api/v2/hifly/account/credit"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }
  
  response = requests.get(url, headers=headers)
  print(response.json())
  

  cURL Example:

  curl -X GET "https://hfw-api.hifly.cc/api/v2/hifly/account/credit" \
     -H "Authorization: Bearer YOUR_TOKEN"
  

• Response Example:

  {
    "code": 0,
    "message": "",
    "left": 10000,
    "request_id": "req123456789"
  }
  

Error Codes