Media Service API v1

REST API for image upload with automatic resizing and secure, Range-capable video streaming.

Quick start

1. Register an account for your application.
2. Wait for an administrator to approve the account.
3. Create an API token on the API Tokens page.
4. Upload a file and use the returned URLs:

curl -X POST https://video.digibhai.store/api/v1/media \
  -H "Authorization: Bearer $MEDIA_TOKEN" \
  -H "Accept: application/json" \
  -F "file=@photo.jpg" \
  -F "visibility=private"

The Media Lab lets you try every endpoint from the browser.

Accounts & approval

The service is multi-tenant: every account represents one consuming application and only sees its own media. New registrations must be approved by an administrator.

A blocked account gets a 403 response that says why. errors.account_status is pending, suspended or expired:

HTTP/1.1 403 Forbidden
{
  "success": false,
  "message": "Your account is pending approval by an administrator.",
  "errors": { "account_status": ["pending"] }
}

Subscription & storage quota

An administrator can give an account a subscription end date and a storage quota. Both are shown on your dashboard and returned by GET /auth/me.

• Subscription: after the end date the account is expired. Nothing is deleted, and access returns as soon as the administrator extends it.
• Storage quota: the total of your originals and variants. An upload that would exceed it is rejected with 422 (Storage quota exceeded on file). Delete media to free space.

Administrator accounts manage the service and cannot use this API: they get 403 with errors.account_type = ["admin"].

Authentication

Send a personal access token with every request:

Authorization: Bearer 12|pRq8...

Abilities

A request needs the ability and ownership of the media. A token missing an ability gets 403. Invalid, revoked or expired tokens get 401.

Responses & errors

Every JSON response uses the same envelope:

// success
{ "success": true, "data": { ... }, "message": null }

// lists add pagination
{ "success": true, "data": [ ... ], "message": null,
  "meta": { "current_page": 1, "per_page": 20, "total": 57, "last_page": 3, "next_page_url": "...", "prev_page_url": null } }

// error
{ "success": false, "message": "Validation failed", "errors": { "file": ["The file is not a valid image."] } }

errors is always an object: field name → list of messages, or {} for errors that are not about a field.

Every response carries an X-Request-Id header. Send your own to correlate logs across services.

Endpoints overview

/media accepts images and videos. /images and /videos behave the same but only accept or return that type.

Auth endpoints

curl -X POST https://video.digibhai.store/api/v1/auth/tokens -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"email":"dev@app.com","password":"secret","token_name":"nextjs-prod","abilities":["media:read","media:write"]}'

201 Created
{ "success": true, "message": "Token issued.",
  "data": { "token": "3|Xy...", "token_type": "Bearer", "abilities": ["media:read","media:write"], "expires_at": "2026-11-01T10:00:00+00:00" } }

{ "success": true, "message": null, "data": {
  "user": { "id": 12, "name": "Web app", "email": "dev@app.com", "company": "Acme", "status": "approved",
            "subscription_ends_at": "2027-01-31T23:59:59+00:00",        // null = no end date
            "storage": { "used_bytes": 734003200, "limit_bytes": 2147483648 } },   // limit null = unlimited
  "token": { "name": "nextjs-prod", "abilities": ["media:read"], "expires_at": "…", "last_used_at": "…" }
} }

Upload

Media object

{
  "id": "9f1c1b8e-3a47-4d0b-9b0e-1b8d6f0a2c11",
  "type": "image",                     // image | video
  "visibility": "private",             // private | public
  "status": "ready",                   // pending | processing | ready | failed
  "original_filename": "holiday.jpg",
  "mime_type": "image/jpeg",
  "extension": "jpg",
  "size": 2483117,                     // bytes
  "checksum": "5d41402a…",             // SHA-256 of the original
  "width": 4000, "height": 3000,
  "duration": null,                    // seconds (videos)
  "metadata": {},                      // videos: video_codec, audio_codec, bitrate, frame_rate, container, extractor
  "variants": [
    { "name": "thumbnail", "width": 150, "height": 113, "size": 4821, "mime_type": "image/webp", "url": "…" }
  ],
  "urls": { "thumbnail": "…", "small": "…", "medium": "…", "large": "…", "original": "…" },  // videos: see below
  "urls_expire_at": "2026-10-01T13:00:00+00:00",   // private media only
  "failure_reason": null,
  "processed_at": "…", "created_at": "…", "updated_at": "…"
}

For private media every URL is a temporary signed URL that works directly in <img> / <video>. Refresh it before urls_expire_at. For public media, URLs are stable and CDN-cacheable.

urls only lists what can be fetched right now, so check a key before using it:

• Images: original at once; the variants appear when status is ready.
• Videos: empty until ready, then original and stream. Poster thumbnails (thumbnail, small, medium, large, taken from one frame) are added only when FFmpeg is installed on the server.

List, get, update, delete

{ "visibility": "public" }

Signed URLs

{ "success": true, "data": { "url": "https://video.digibhai.store/api/v1/videos/9f1c…/stream?expires=1790000000&signature=…", "variant": "stream", "expires_at": "…" } }

• The signature (HMAC-SHA256) covers the path and query, so it can't be reused for other media or variants, and the expiry can't be changed.
• No Authorization header is needed. It works for every Range request a video player makes.
• A variant the media does not have → 422. Invalid or expired signature → 403. Suspended or expired account → 404.

Image variants

Video streaming & HTTP Range

# Partial content
GET /api/v1/videos/{id}/stream
Range: bytes=0-1048575

HTTP/1.1 206 Partial Content
Content-Type: video/mp4
Content-Range: bytes 0-1048575/26215007
Content-Length: 1048576
Accept-Ranges: bytes

# Not satisfiable
GET /api/v1/videos/{id}/stream
Range: bytes=999999999-

HTTP/1.1 416 Range Not Satisfiable
Content-Range: bytes */26215007

# No Range header → 200 OK, whole file,
# Content-Length: 26215007

<!-- Browsers and native players send Range requests automatically -->
<video src="SIGNED_OR_PUBLIC_STREAM_URL" controls preload="metadata"></video>

Caching headers

ETag is the SHA-256 of the served file. Send it back as If-None-Match to get 304.

Rate limits

When a limit is hit: 429 with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining.

CORS

Browser clients may call the API cross-origin. Allowed request headers: Authorization, Content-Type, Accept, Range, If-Range, If-None-Match, If-Modified-Since, X-Request-Id, X-Requested-With. Exposed response headers: Accept-Ranges, Content-Range, Content-Length, ETag, Last-Modified, X-Request-Id, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining.

Integration examples

JavaScript (fetch)

const API = 'https://media.example.com/api/v1';

async function upload(file, token) {
  const body = new FormData();
  body.append('file', file);            // don't set Content-Type yourself
  body.append('visibility', 'private');
  const res = await fetch(`${API}/media`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
    body,
  });
  const json = await res.json();
  if (!json.success) throw new Error(json.message);
  return json.data;                      // media object
}

async function waitUntilReady(id, token) {
  for (;;) {
    const { data } = await (await fetch(`${API}/media/${id}`, {
      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
    })).json();
    if (data.status === 'ready') return data;
    if (data.status === 'failed') throw new Error(data.failure_reason);
    await new Promise((r) => setTimeout(r, 1000));
  }
}

Next.js (App Router, server-side token)

// lib/media.ts
import 'server-only';
export async function getMedia(id: string) {
  const res = await fetch(`${process.env.MEDIA_API_URL}/media/${id}`, {
    headers: { Authorization: `Bearer ${process.env.MEDIA_API_TOKEN}`, Accept: 'application/json' },
    next: { revalidate: 900 },           // signed URLs live ~1h
  });
  return res.ok ? (await res.json()).data : null;
}

// app/photos/[id]/page.tsx
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const media = await getMedia((await params).id);
  return media.type === 'video'
    ? <video src={media.urls.stream} controls preload="metadata" />
    : <img src={media.urls.large ?? media.urls.original} alt={media.original_filename} />;
}

React

export function ResponsiveImage({ media, width }) {
  const srcSet = media.variants.map((v) => `${v.url} ${v.width}w`).join(', ');
  return <img src={media.urls.medium ?? media.urls.original} srcSet={srcSet}
              sizes={`${width}px`} width={width} alt="" loading="lazy" />;
}

export const VideoPlayer = ({ media }) =>
  <video src={media.urls.stream} controls preload="metadata" playsInline />;

React Native

const body = new FormData();
body.append('file', { uri: asset.uri, name: asset.fileName ?? 'upload.jpg', type: asset.mimeType ?? 'image/jpeg' });
await fetch(`${API}/media`, { method: 'POST', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' }, body });

<Image source={{ uri: media.urls.small }} style={{ width: 320, aspectRatio: media.width / media.height }} />
<Video source={{ uri: media.urls.stream }} useNativeControls />   // expo-av / react-native-video

OpenAPI spec

An OpenAPI 3.1 description of every endpoint, including the /images and /videos forms, is available for Postman, Insomnia, or client generators: