Nexakaunt Media v1.0
Sign In Register

API Documentation

Base URL: /api

Welcome to the official developer reference for the Nexakaunt Media Service. This REST microservice centralizes image optimization, asynchronous video transcoding via background workers, document storage, and dynamic on-the-fly image transformations.

Authentication & Gateway Headers

Microservice access control and identity injection

This service runs behind the Nexakaunt API Gateway. The Gateway handles main user authentication and forwards client identity headers to the media service:

Header Description Required
X-User-Id UUID of the requesting user (stored as media owner_id) Yes (for private uploads/reads)
X-Company-Id UUID of the company/tenant (used for quota calculations and company-wide access) Optional
Authorization Sanctum Bearer token (Bearer 1|...) used for Developer API key management endpoints Only for developer console
POST

/api/media/upload

Upload images, videos, or document files. Images are synchronously optimized and converted to WebP. Videos are stored raw and an asynchronous transcoding job is queued.

Multipart Parameters
Field Type Required Description
images[] File Array Yes Array of media files (Max 50MB per file)
access_type String No public or private (default: public)
disk String No public, local, s3, or minio
Request Examples
curl -X POST https://media.nsantosh.com/api/media/upload \
  -H "X-User-Id: 9d5e8a7b-1234-5678-90ab-cdef12345678" \
  -H "X-Company-Id: 442e8a7b-1234-5678-90ab-cdef12345678" \
  -F "images[]=@/path/to/photo.jpg" \
  -F "access_type=private"
const formData = new FormData();
formData.append('images[]', fileInput.files[0]);
formData.append('access_type', 'private');

const response = await fetch('/api/media/upload', {
  method: 'POST',
  headers: {
    'X-User-Id': '9d5e8a7b-1234-5678-90ab-cdef12345678',
    'X-Company-Id': '442e8a7b-1234-5678-90ab-cdef12345678'
  },
  body: formData
});
const data = await response.json();
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-User-Id' => '9d5e8a7b-1234-5678-90ab-cdef12345678',
    'X-Company-Id' => '442e8a7b-1234-5678-90ab-cdef12345678',
])->attach(
    'images[]', file_get_contents($filePath), 'photo.jpg'
)->post('https://media.nsantosh.com/api/media/upload', [
    'access_type' => 'private'
]);
Success Response (201 Created)
{
  "message": "1 file(s) uploaded successfully",
  "data": [
    {
      "id": "9d5e8a7b-1234-5678-90ab-cdef12345678",
      "url": "https://media.nsantosh.com/api/media/9d5e8a7b-1234-5678-90ab-cdef12345678/serve",
      "filename": "photo.webp",
      "mime_type": "image/webp",
      "size": 245678,
      "processing_status": "completed",
      "thumbnail_url": null,
      "created_at": "2026-07-30T15:45:00.000000Z"
    }
  ]
}
GET

/api/media/{id}

Retrieve complete metadata for a specific media record by UUID. Private files require X-User-Id matching the owner or company.

GET

/api/media/{id}/serve

Streams the raw file with HTTP caching headers (ETag, Cache-Control). Supports range requests for video seeking and instant image resize parameters.

Query Parameters
Parameter Type Description Example
w Integer Target width in pixels ?w=400
h Integer Target height in pixels ?h=300
q Integer WebP quality level (1-100) ?q=80
thumbnail Boolean Set to 1 to retrieve video thumbnail poster ?thumbnail=1
token String Signed 1-hour HMAC view token for private browser images ?token=hmac...
GET

/api/media/{id}/view-token

Browser <img> tags cannot send custom HTTP headers. Calling this endpoint returns a short-lived (1h) signed token that can be appended to serve URLs via ?token=.

GET

/api/media/{id}/status

Poll asynchronous video processing status. Status values:

pending Waiting for queue
processing FFmpeg transcoding
completed Ready for playback
failed Transcode error
GET

/api/media/stats/usage

Get real-time storage quota usage for the company passed in X-Company-Id. Returns total bytes used, company quota cap, and total media counts.

Live API Request Tester

Response Output