​
Overview

All Unifically API models support the optional callback_url parameter. When provided, the API will send a POST request to your specified URL when a task completes or fails.
The callback_url parameter is available on all generate endpoints across image, video, and audio models.

​
How It Works

  1. Include callback_url in your generate request
  2. The API returns a task_id immediately
  3. When the task completes or fails, a POST request is sent to your callback URL
  4. Your server receives the result without needing to poll

​
Request Parameter

​
callback_url
string
Publicly accessible URL to receive a POST request when the task completes or fails.Example: "https://your-server.com/webhook/unifically"

​
Example Request

curl -X POST "https://api.unifically.com/sora-2/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cat playing piano",
    "duration": 10,
    "callback_url": "https://your-server.com/webhook/unifically"
  }'

​
Callback Responses

​
Successful Task

When a task completes successfully, your callback URL receives: 
{
  "status": "completed",
  "task_id": "0f6c12a7-cfe8-40d3-98e1-874917affba7",
  "data": {
    "video_url": "https://files.storagecdn.online/video/4766236a-a37c-40ac-a736-1dd03ee52740.mp4"
  }
}
The data object contains the output URL. Depending on the task type, this will be image_url, video_url, or audio_url.

​
Output by Task Type

Task TypeOutput Field
Image Generationdata.image_url
Video Generationdata.video_url
Audio Generationdata.audio_url
Access the output using data.image_url, data.video_url, or data.audio_url depending on the task type.

​
Failed Task

When a task fails, your callback URL receives: 
{
  "status": "failed",
  "task_id": "198b30f1-7d71-48d5-802d-bceddd4e6b86",
  "error_message": "[Content policy violation] Your request contains inappropriate content or generated inappropriate content. Please check your request and try again. If you think this is a mistake, please contact us."
}

​
Response Fields

​
status
string
Task status: completed or failed
​
task_id
string
Unique identifier for the task
​
data
object
Output data (only present on success)
​
image_url
string
Generated image URL (for image tasks)
​
video_url
string
Generated video URL (for video tasks)
​
audio_url
string
Generated audio URL (for audio tasks)
​
error_message
string
Error description (only present on failure)

​
Handling Callbacks

​
Example Server (Node.js)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/unifically', (req, res) => {
  const { status, task_id, data, error_message } = req.body;
  
  if (status === 'completed') {
    // Handle successful task
    const outputUrl = data.video_url || data.image_url || data.audio_url;
    console.log(`Task ${task_id} completed: ${outputUrl}`);
    // Process the result...
  } else if (status === 'failed') {
    // Handle failed task
    console.error(`Task ${task_id} failed: ${error_message}`);
    // Handle the error...
  }
  
  // Respond with 200 to acknowledge receipt
  res.status(200).send('OK');
});

app.listen(3000);

​
Example Server (Python)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/unifically', methods=['POST'])
def handle_callback():
    data = request.json
    
    if data['status'] == 'completed':
        # Handle successful task
        output = data['data']
        output_url = output.get('video_url') or output.get('image_url') or output.get('audio_url')
        print(f"Task {data['task_id']} completed: {output_url}")
        # Process the result...
    else:
        # Handle failed task
        print(f"Task {data['task_id']} failed: {data.get('error_message')}")
        # Handle the error...
    
    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

​
Best Practices

Respond Quickly

Return a 200 status within 5 seconds to acknowledge receipt

Use HTTPS

Always use HTTPS URLs for security

Verify Task ID

Store and verify task IDs to prevent replay attacks

Handle Retries

Implement idempotent handlers in case of duplicate callbacks
Ensure your callback endpoint is publicly accessible and can handle POST requests with JSON payloads.