Nexakaunt Media v1.0

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

The Media Service uses a 3-tier multi-tenancy architecture. A single developer/master account can service hundreds of client companies with strict data isolation:

  • Tier 1 (Master Account / owner_id): Authenticated via your Master API Key or Bearer Token. Manages quotas and billing.
  • Tier 2 (Tenant Company / company_id): Sent via X-Company-Id. Media is strictly isolated per company so Company A never sees Company B's media.
  • Tier 3 (End User or Driver / uploader_id): Sent via X-User-Id. Tracks the specific driver or staff member who uploaded the file.
Header Description Required
Authorization Primary Master Developer authentication: Bearer mk_... (or Sanctum token for web console) Yes*
X-Api-Key / X-Media-Api-Key Header aliases for the Media Service API Key (mk_...) Yes*
X-Company-Code / X-Company-Id Tenant / Company Code (e.g. XR11proMAX). Strictly scopes uploads and queries to that company. Recommended
X-User-Id Identifier of the driver, staff member, or customer (persisted strictly as uploader_id) Optional
CRITICAL: Direct Uploads from Mobile Apps & Frontends

X-User-Id DOES NOT authenticate requests. Any upload from mobile apps (Flutter / React Native) directly to Media Service must supply the organization's Media API key in the X-Api-Key or Authorization header. Sending only an application auth token will result in 401 Unauthorized.

Direct Connection Guide (Without SDK)

Zero Dependencies

Connect directly using standard HTTP, cURL, or S3 protocol

Endpoint: https://media-api.atithisewa.com

You do not need to install an SDK to communicate with the Media Service. The entire service runs on standard REST endpoints and MinIO/S3 compatible storage. Any framework, language, or frontend can connect directly.

1. Laravel Direct HTTP (No SDK) Illuminate\Support\Facades\Http

Upload directly from Auth, Finance, or Fleet services using standard Laravel HTTP client:

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'Bearer ' . env('MEDIA_SERVICE_API_KEY'),
    'X-User-Id'     => (string) auth()->id(),
    'X-Company-Id'  => (string) auth()->user()->company_id,
])->attach(
    'images', 
    file_get_contents($request->file('avatar')->getRealPath()), 
    $request->file('avatar')->getClientOriginalName()
)->post('https://media-api.atithisewa.com/api/media/upload', [
    'access_type' => 'public', // or 'private'
]);

$fileId = $response->json('data.0.id');
2. Direct URLs in HTML / React / Blade (0ms Latency) Zero API roundtrips

Display responsive images or stream video directly via URL parameters without any API call:

<!-- Responsive Image with Dynamic Resize and Quality -->
<img src="https://media-api.atithisewa.com/api/images/{FILE_ID}/serve?w=400&h=300&q=80" alt="Avatar" />

<!-- Direct File Download -->
<a href="https://media-api.atithisewa.com/api/media/{FILE_ID}/download">Download File</a>

<!-- Smooth Video Streaming with HTTP 206 Partial Range seeking -->
<video controls src="https://media-api.atithisewa.com/api/videos/{FILE_ID}/serve"></video>
3. Direct cURL Command CLI / Postman
curl -X POST https://media-api.atithisewa.com/api/media/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-User-Id: user_123" \
  -F "images=@/path/to/invoice.pdf" \
  -F "access_type=private"
4. Standard AWS S3 Driver via Laravel Filesystem config/filesystems.php

Connect directly using the MinIO Access Key & Secret Key minted in your Media Console:

// In config/filesystems.php of any service
'nexakaunt_s3' => [
    'driver'                  => 's3',
    'key'                     => env('AWS_ACCESS_KEY_ID'),
    'secret'                  => env('AWS_SECRET_ACCESS_KEY'),
    'region'                  => 'us-east-1',
    'bucket'                  => env('AWS_BUCKET', 'nexakaunt-media'),
    'endpoint'                => env('AWS_ENDPOINT', 'https://media-api.atithisewa.com:9000'),
    'use_path_style_endpoint' => true,
],

Official SDKs Integration Guide

3-Tier Operations

Strongly typed SDKs for PHP/Laravel and JavaScript/TypeScript

packages/php-sdk & packages/js-sdk
PHP & Laravel SDK nexakaunt/media-client
PSR-4

Auto-discovering Laravel package with NexakauntMedia Facade and typed MediaAsset DTO.

1. Configure in .env
MEDIA_SERVICE_URL=https://media-api.atithisewa.com
MEDIA_SERVICE_API_KEY=mk_live_your_secret_key
2. Usage in Controllers
use Nexakaunt\Media\Facades\NexakauntMedia;

// Tier 2: Upload with user/tenant isolation
$asset = NexakauntMedia::upload(
    $request->file('avatar'),
    folder: 'avatars',
    isPrivate: false,
    ownerId: (string) auth()->id()
);

// Tier 1: 0ms Instant URL generation
$thumbUrl = NexakauntMedia::thumbnailUrl($asset->id, 200);

// Private short-lived signed view URL
$signedUrl = NexakauntMedia::getPrivateViewUrl($asset->id, expiryMinutes: 15);
JavaScript / TypeScript SDK @nexakaunt/media-sdk
ESM / TS

Zero-dependency TypeScript client for React, Vue, Next.js, and Node.js with client-side security safeguards.

1. Configure in Frontend (.env)
NEXT_PUBLIC_MEDIA_URL=https://media-api.atithisewa.com
// Never expose Master API Key in browser!
2. Usage in React / Vue / Next.js
import { NexakauntMedia } from '@nexakaunt/media-sdk';

// Client-safe init (No secrets in frontend bundle)
const media = new NexakauntMedia({
  baseUrl: process.env.NEXT_PUBLIC_MEDIA_URL,
});

// Tier 1: 0ms instant thumbnail (zero network trip)
export function Avatar({ fileId }) {
  const url = media.thumbnailUrl(fileId, 120);
  return <img src={url} className="rounded-full w-10 h-10" />;
}
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

When media is uploaded with access_type: private, direct unauthenticated access to /serve is rejected with 403 Forbidden. Standard browser <img> tags and mobile widgets (Image.network) cannot send custom HTTP headers. Calling this endpoint generates a short-lived (1-hour) signed HMAC view token and returns a pre-signed URL with ?token=... ready for direct display.

Required Headers
Header Required Description
Authorization Yes Master API Key formatted as Bearer <API_KEY>
X-Company-Id Conditional Tenant company identifier matching the media item's company
X-User-Id Conditional User UUID matching the media item's owner
Client Implementation Examples
// 1. Fetch pre-signed temporary URL:
final res = await dio.get(
  'https://media-api.atithisewa.com/api/images/$mediaId/view-token',
  options: Options(headers: {
    'Authorization': 'Bearer $apiKey',
    'X-Company-Id': companyCode,
  }),
);
final String signedUrl = res.data['data']['url'];

// 2. Render directly in Flutter widget:
Image.network(
  signedUrl,
  fit: BoxFit.cover,
  errorBuilder: (context, error, stack) => Icon(Icons.broken_image),
);
curl -X GET "https://media-api.atithisewa.com/api/media/019482fa-bc44-7128-98e1-d2e46b9a1012/view-token" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Company-Id: comp_fleet_101"
const res = await fetch(`https://media-api.atithisewa.com/api/media/${mediaId}/view-token`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Company-Id': companyId
  }
});
const { data } = await res.json();

// Directly assign to HTML Image element:
document.getElementById('docPreview').src = data.url;
use Illuminate\Support\Facades\Http;

// Backend signs URL and passes it to the mobile client
$response = Http::withHeaders([
    'Authorization' => 'Bearer ' . $apiKey,
    'X-Company-Id'  => $companyCode,
])->get("https://media-api.atithisewa.com/api/media/{$mediaId}/view-token");

$signedUrl = $response->json('data.url');
Success Response (200 OK)
{
  "data": {
    "url": "https://media-api.atithisewa.com/api/media/019482fa-bc44-7128-98e1-d2e46b9a1012/serve?token=eyJtZWRpYUl...",
    "serve_url": "/api/media/019482fa-bc44-7128-98e1-d2e46b9a1012/serve?token=eyJtZWRpYUl...",
    "filename": "citizenship_card.webp",
    "mime_type": "image/webp",
    "expires_in": 3600
  }
}
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