Media API Reference

The Media API allows you to create media records, upload media files via a pre-signed S3 URL, fetch media information, and delete media.

This page documents all available Media API endpoints, including request/response schemas, examples, and error codes.

Overview

The Media API supports the following operations:

Endpoint	Method	Description	Request Type
`/media`	POST	Create media record + get S3 upload URL	Mutation
`/media`	GET	List all media belonging to the user	Query
`/media/{mid}`	GET	Fetch a single media record	Query
`/media/{mid}`	DELETE	Delete a media record	Mutation

Authenta media uploads use a two-step upload process:

POST /media → Create media record + receive S3 upload URL
PUT to S3 → Upload the actual file

Processing begins automatically after upload.

Authentication

All endpoints require:

x-client-id: <your_client_id>
x-client-secret: <your_client_secret>

See: /api/authentication

1. Create Media Record

`POST /media`

Creates a new media record and returns a pre-signed S3 URL to upload the actual file.

This is a Mutation request.

Request Body

interface CreateMediaRequest {
  name: string;
  contentType: string; // e.g. "video/mp4"
  size: number; // file size in bytes
  modelType: 'DF-1' | 'AC-1' | 'FD-1'; // e.g. "DF-1"
}

Example

curl -X POST "https://platform.authenta.ai/api/media" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "video_sample",
    "contentType": "video/mp4",
    "size": 1048576,
    "modelType": "DF-1"
  }'

Response

interface CreateMediaResponse {
  mid: string; // media ID
  name: string;
  type: 'Video' | 'Image';
  status: 'INITED' | 'UPLOADED' | 'PROCESSED';
  modelType: 'DF-1' | 'AC-1' | 'FD-1';
  createdAt: string;
  uploadUrl: string;
}

Example Response

{
  "mid": "692f406f9f68d4b70080bb80",
  "name": "video_sample",
  "type": "Video",
  "status": "INITED",
  "modelType": "DF-1",
  "createdAt": "2025-12-02T19:39:27.525Z",
  "uploadUrl": "https://authenta-storage.s3.us-east-1.amazonaws.com/users/692d5c1d0ac955973b9583fc/media/692f406f9f68d4b70080bb80/original.media?..."
}

Step 2: Upload File to S3

Upload the file to the returned URL:

curl -X PUT "https://signed-s3-url" \
  -H "Content-Type: video/mp4" \
  --data-binary "@./video.mp4"

Notes:

Upload must match the contentType and size provided.
Uploading to S3 does not count against API quotas.
Processing begins automatically after upload.

2. List All Media

`GET /media`

Fetches all media records for the authenticated user.

This is a Query request.

Example

curl -X GET "https://platform.authenta.ai/api/media" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response

interface MediaResponse {
  mid: string;
  name: string;
  type: 'Video' | 'Image';
  status: 'INITED' | 'UPLOADED' | 'PROCESSED';
  modelType: 'DF-1' | 'AC-1' | 'FD-1';
  createdAt: string;
  srcURL?: string;
 
  // Fields for video content
  faces?: number; // Number of faces in the video
  deepFakes?: number; // Number of deep fakes in the video
 
  // Fields for image content
  fake?: boolean; // Whether the image is fake or not
  confidence?: number; // Confidence of the inference
}
 
interface ListMediaResponse {
  limit: number;
  offset: number;
  total: number;
  data: MediaResponse[];
}

Example Response

{
  "limit": 3,
  "offset": 0,
  "total": 1,
  "data": [
    {
      "mid": "692f406f9f68d4b70080bb80",
      "name": "video_sample",
      "type": "Video",
      "status": "PROCESSED",
      "modelType": "DF-1",
      "createdAt": "2025-12-02T19:39:27.525Z",
      "srcURL": "https://authenta-storage.s3.us-east-1.amazonaws.com/users/692d5c1d0ac955973b9583fc/media/692f406f9f68d4b70080bb80/original.media?...",
      "faces": 1,
      "deepFakes": 1
    }
  ]
}

3. Get a Media Record

`GET /media/{mid}`

Fetches details about a single media item.

This is a Query request.

Example

curl -X GET "https://platform.authenta.ai/api/media/692f406f9f68d4b70080bb80" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response

interface VideoParticipantResponse {
  id: number;
  fake: boolean;
  heatmap?: string;
}
 
interface MediaDetailsResponse {
  mid: string;
  name: string;
  type: 'Video' | 'Image';
  status: 'INITED' | 'UPLOADED' | 'PROCESSED';
  modelType: 'DF-1' | 'AC-1' | 'FD-1';
  createdAt: string;
 
  srcURL?: string;
  resultURL?: string;
 
  // Fields for video content
  faces?: number;
  deepFakes?: number;
  participants?: VideoParticipantResponse[];
 
  // Fields for Image content
  fake?: boolean;
  confidence?: number;
}

Example Response

{
  "mid": "692f406f9f68d4b70080bb80",
  "name": "video_sample",
  "type": "Video",
  "status": "PROCESSED",
  "modelType": "DF-1",
  "createdAt": "2025-12-02T19:56:49.353Z",
  "srcURL": "https://authenta-storage.s3.us-east-1.amazonaws.com/users/692d5c1d0ac955973b9583fc/media/692f406f9f68d4b70080bb80/original.media?...",
  "faces": 1,
  "deepFakes": 1,
  "participants": [
    {
      "id": 0,
      "fake": true,
      "heatmap": "https://authenta-storage.s3.us-east-1.amazonaws.com/users/692d5c1d0ac955973b9583fc/media/692f406f9f68d4b70080bb80/processed_face_0.media?..."
    }
  ],
  "resultURL": "https://authenta-storage.s3.us-east-1.amazonaws.com/users/692d5c1d0ac955973b9583fc/media/692f406f9f68d4b70080bb80/result.json?..."
}

4. Delete Media

`DELETE /media/{mid}`

Deletes a media record belonging to the authenticated user.

This is a Mutation request.

Example

curl -X DELETE "https://platform.authenta.ai/api/media/692f406f9f68d4b70080bb80" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Notes

This removes the media record from Authenta.
Does not consume credits.
Requires delete permission. If missing:

IAM002 – You are not authorized

Media Status Lifecycle

A media item goes through several statuses:

Status	Meaning
`INITED`	Record created but file not uploaded
`UPLOADED`	File uploaded to S3, processing is running
`PROCESSED`	Results are available

You may poll GET /media/{mid} until status becomes PROCESSED.

Error Codes

IAM001 — Invalid Credentials

Returned when the Client ID or Client Secret is missing or incorrect.

{
  "code": "IAM001",
  "type": "UNAUTHENTICATED",
  "message": "You are not authenticated"
}

IAM002 — Insufficient Permissions

Returned when your API key does not have the required permissions.

{
  "code": "IAM002",
  "type": "UNAUTHORIZED",
  "message": "You are not authorized"
}

AA001 — API Limit Reached

Returned when your Query or Mutation quota is exceeded.

{
  "code": "AA001",
  "type": "CLIENT_ERROR",
  "message": "API limit reached"
}

U007 — Insufficient Credits

Returned when media processing cannot start due to insufficient credits.

{
  "code": "U007",
  "type": "CLIENT_ERROR",
  "message": "Insufficient credits"
}

TypeScript Type Reference

Below is a simplified reference for the media-related interfaces used in the API:

type MediaStatus = 'INITED' | 'UPLOADED' | 'PROCESSED';
 
interface MediaResponse {
  mid: string;
  name: string;
  type: 'Video' | 'Image';
  status: 'INITED' | 'UPLOADED' | 'PROCESSED';
  modelType: 'DF-1' | 'AC-1' | 'FD-1';
  createdAt: string;
  srcURL?: string;
}

Summary

Use POST /media to create a media record and get an S3 upload URL
Upload the actual file directly to S3
Poll GET /media/{mid} for processing status
Use DELETE /media/{mid} to remove media
Quotas apply to GET/POST/DELETE; credits apply only to processing
Error codes follow a structured JSON format

Next Steps

Authentication → /api/authentication
Making API Calls → /api/making-api-calls
Quotas & Credits → /api/quotas-and-credits
Use the Postman Collection → /api/postman-collection