Retroiva AI API Reference

The Retroiva AI API provides programmatic access to our GPU-accelerated video restoration pipeline. Integrate upscaling, frame interpolation, and denoising directly into your video CMS, DAM, or mobile application.

Base URL: https://api.retroiva.com

Authentication

Authenticate your requests by including your secret API key in the Authorization header. You can manage your keys in the Dashboard.

BASH 
curl https://api.retroiva.com/v2/enhance \
  -H "Authorization: Bearer sk_live_8923489234..." \
  -H "Content-Type: application/json"

Versioning

The API is currently in version 2.1 (`v2`). We follow semantic versioning for our endpoints. Breaking changes will be introduced in a new version namespace (e.g., `/v3/`).

Errors

Retroiva AI uses conventional HTTP response codes to indicate the success or failure of an API request.

Code Description
200 OK The request was successful.
400 Bad Request Invalid parameters were provided (e.g., unsupported video format or missing URL).
401 Unauthorized API key is missing or invalid.
429 Too Many Requests You have exceeded your rate limit.
500 Server Error An error occurred on Retroiva AI's servers. We have been notified.

Rate Limits

Rate limits are applied per API key. Information about your current usage is included in the headers of every response.

Standard Tier
100 req/min
Burst: 150
Enterprise Tier
5,000 req/min
Burst: 7,500

Check the X-RateLimit-Remaining header to see how many requests you have left in the current window.

The Job Object

This object represents a video enhancement task.

{
  "id": "job_123456",
  "status": "processing", // queued, processing, completed, failed
  "input_url": "https://...",
  "output_url": null,
  "created_at": 1698220000,
  "completed_at": null,
  "error": null
}
POST

/v2/enhance

Creates a new enhancement job. The video must be accessible via a public URL (S3, GCS, Azure Blob, etc.).

Parameters

FieldTypeDescription
video_urlstringPublic URL of source video.
presetstringOne of: `cinematic`, `social`, `archive`, `general`.
webhook_urlstringURL to receive POST request when job completes.

Example Request

cURL Python Node.js 
curl -X POST https://api.retroiva.com/v2/enhance \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://s3.amazonaws.com/my-bucket/raw.mp4",
    "preset": "cinematic",
    "upscale_factor": 4
  }'
GET

/v2/jobs/{job_id}

Retrieve the current status and progress of a specific job.

{
  "id": "job_892348923",
  "status": "processing",
  "progress": 0.45,
  "eta_seconds": 120
}
GET

/v2/jobs

List all jobs created by your API key. Supports pagination.

{
  "data": [
    { "id": "job_1", "status": "completed" },
    { "id": "job_2", "status": "processing" }
  ],
  "has_more": true,
  "next_cursor": "job_2"
}
GET

/v2/jobs/{job_id}/download

Get the temporary signed URL to download the enhanced video. Links expire after 24 hours due to our Zero-Retention policy.

POST

/v2/jobs/{job_id}/cancel

Stops processing for a job. If the job is already completed, this has no effect.

Webhooks

Retroiva AI sends `POST` requests to your endpoint when events occur. Retroiva AI will retry failed webhooks up to 5 times with exponential backoff.

Event: job.completed

Triggered when enhancement is finished and the download URL is ready.

Event: job.failed

Triggered if the video could not be processed (e.g., corrupt input).

Signature Verification

To verify that a webhook was sent by Retroiva AI, calculate the HMAC SHA256 of the request body using your webhook secret and compare it to the `X-retroiva-Signature` header.

Node.js
const crypto = require('crypto');

function verifySignature(req) {
  const signature = req.headers['x-retroiva-signature'];
  const hash = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');
    
  return signature === hash;
}