AI-Powered Video Reframe API for businesses

API 1: Submit Reframe Job

Parameters:

• callback_url - URL to receive job completion notification.
• video_url - Public URL to the video file (required)
• api_key - Your API access key (required)

Response: Returns JSON with either job_id or error field.

API 2: Check Job Status

Parameters:

• job_id - The job ID returned from the reframe API (required)
• api_key - Your API access key (required)

Response Fields:

• job_id - The unique job identifier
• status - Current job status (in_queue, processing, success, or failed)
• callback_url - The callback URL you provided
• job_started_unix - Unix timestamp when job started processing
• job_completed_unix - Unix timestamp when job completed
• error_message - Error message if job failed (null otherwise)
• reframed_video_url - URL to download the reframed video (if successful)
• callback_response_error - Error returned by your callback endpoint (null if no error)
• failed_callbacks_count - Number of failed webhook delivery attempts
• last_callback_unix - Unix timestamp of last webhook attempt

Status Values:

• in_queue - Job is waiting to be processed
• processing - Job is currently being processed
• success - Job completed successfully
• failed - Job failed

Callbacks / Webhooks

When you provide a callback_url in your reframe request, we will send a POST request to that URL when the job completes (either successfully or with an error).

Webhook Behavior:

• We send a POST request to your callback URL
• We expect a 200 OK HTTP response code to acknowledge receipt
• If we don't receive HTTP 200, we retry within 10 mins up to 3 times
• Once HTTP 200 is received, we do not retry (even if your response contains an error)

Webhook Payload:

The POST request body contains the same JSON fields as the Job Status API response:

• status - Current job status (in_queue, success, or failed)
• job_id - The unique job identifier
• callback_url - The callback URL you provided
• job_started_unix - Unix timestamp when job started processing
• job_completed_unix - Unix timestamp when job completed
• error_message - Error message if job failed (null otherwise)
• reframed_video_url - URL to download the reframed video (if successful)

Your Response Format:

Your callback endpoint should always return HTTP 200 to acknowledge receipt. You can optionally return a JSON response to report processing errors:

• success - boolean - true if you processed the callback successfully
• error - string (optional) - error code if success is false
• error_message - string (optional) - human-readable error message

Note: We record your error response for debugging purposes but do not retry the webhook.

Example Webhook Handler (Node.js):

app.post('/webhook/croply', async (req, res) => {
  const { status, job_id, reframed_video_url, error_message } = req.body;
  
  try {
    if (status === 'success') {
      console.log(`Job ${job_id} completed: ${reframed_video_url}`);
      // Download and process the reframed video
      await downloadVideo(reframed_video_url);
    } else if (status === 'failed') {
      console.error(`Job ${job_id} failed: ${error_message}`);
    }
    
    // Return 200 OK with success
    res.status(200).json({ success: true });
  } catch (err) {
    // Return 200 OK but report the error (Croply will record it)
    res.status(200).json({ 
      success: false, 
      error: 'processing_failed',
      error_message: err.message 
    });
  }
});

Example Webhook Handler (PHP):

<?php
// Always return 200 to acknowledge receipt
http_response_code(200);
header('Content-Type: application/json');

$payload = json_decode(file_get_contents('php://input'), true);
$jobId = $payload['job_id'] ?? null;
$status = $payload['status'] ?? null;

try {
    if ($status === 'success') {
        // Download the reframed video
        $videoUrl = $payload['reframed_video_url'];
        // ... your download logic
    }
    
    echo json_encode(['success' => true]);
} catch (Exception $e) {
    // Report error but don't change HTTP status (still 200)
    echo json_encode([
        'success' => false,
        'error' => 'processing_failed',
        'error_message' => $e->getMessage()
    ]);
}

Code Examples