Get Started With API

Introduction

The JoyPix API allows you to programmatically generate lip-sync videos using our Motion-2 models. This guide will walk you through the basic usage flow and response codes.

Usage Flow

Step 1: Get API Key

Go to the /app/profile page to obtain your JoyPix API Key.

Step 2: Submit Task

Submit a generation task, for example.

POST /v1/lip-sync/motion-2

Header:

Content-Type: application/jsonAuthorization: Bearer ${JoyPix_API_KEY}

Body:

{
  "audio_url": "https://example.com/audio.mp3",
  "image_url": "https://example.com/image.jpg",
  "resolution": "720p",
  "prompt": "the man speak happily",
  "seed": -1
}

Response:

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "task_123456789"
    "status": "submitted"
  }
}

Step 3: Get Task Result

GET /v1/tasks/${task_id}

Header:

Authorization: Bearer ${JoyPix_API_KEY}

Response:

{
    "code": 0,    // int, 200 for success, 4xx, client error, 5xx, server error
    "message": "success", // string, eg.success
    "data": {
        "task_id": "task_123456",         // string, task id
        "inputs": "...",          // string, input params
        "model": "motion-2",           // string, model id
        "status":  "completed",             // string, task status, submitted, processing, completed, failed
        "error": "",      // string, fail reason, when status=failed
        "video_url": "https://joypix-output.s3.amazonaws.com/...",        // string, video url , when status=completed
    }
}

API Reference

Item	Value
Base URL	https://openapi.joypix.ai
Auth Header	Authorization: Bearer ${JoyPix_API_KEY}
Content Type	application/json

Result Data Struct

{
    "code": 0,
    "msg": "xxx",
    "data": {
       "task_id": "task_id_123456",
       "key": "val"
    }
}

Task Status

Status	Description
submitted	Task is queued
processing	Task is running
completed	Task finished successfully
failed	Task failed (check error field)

Error Codes

Code	Description
200	Success
4xx	Client Error
5xxx	Server Error

Note

Generated data is currently stored for 72 hours. Please download it as soon as possible.
Failed tasks will have their consumed credits refunded. (If you encounter any unexpected issues, please contact us at openapi@joypix.ai)
API generation records are retained for 1 month. If you have any questions, please provide feedback within this period.