Get Media

Fetch full details for a single media item by ID, including processed frames, AI-generated captions, detected objects, and tags.

Endpoint

GET /api/media/{mediaId}

Path Parameters

Parameter	Type	Description
`mediaId`	string	The media item's UUID (hyphens stripped)

Headers

Accepts x-api-key or Authorization: Bearer. See Getting Started.

Example Request

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/media/MEDIA_ID"

Response

Status Code: 200 OK

{
  "media": {
    "id": "abc123def456",
    "name": "hero-shot.jpg",
    "type": "image",
    "blob": "https://blob.vercel-storage.com/.../hero-shot.jpg",
    "path": "collectionId.folderId.abc123def456",
    "datasetId": "collectionId",
    "width": 2400,
    "height": 1600,
    "duration": null,
    "sizeBytes": 184320,
    "createdAt": "2026-03-10T14:22:00.000Z",
    "updatedAt": "2026-03-10T14:22:00.000Z",
    "createdById": "userId123",
    "updatedById": null,
    "status": "active",
    "sourceMediaId": null,
    "versionNumber": 1,
    "metadata": {
      "tags": {
        "color": ["red"],
        "category": ["product"]
      },
      "moderation": {
        "status": "approved",
        "categories": [],
        "moderatedAt": "2026-03-10T14:22:01.000Z"
      }
    },
    "frames": [
      {
        "id": "frameId789",
        "timestamp": "0",
        "blob": "https://blob.vercel-storage.com/.../processed.jpg",
        "width": 2400,
        "height": 1600,
        "status": "active",
        "createdAt": "2026-03-10T14:22:05.000Z",
        "mediaId": "abc123def456",
        "captions": [
          {
            "id": "captionId111",
            "text": "A red shoe on a white background.",
            "frameId": "frameId789",
            "createdAt": "2026-03-10T14:22:15.000Z",
            "status": "active"
          }
        ],
        "objects": [
          {
            "id": "objectId222",
            "type": "object",
            "label": "shoe",
            "blob": "https://blob.vercel-storage.com/.../crop-shoe.jpg",
            "status": "active"
          }
        ]
      }
    ],
    "dataset": {
      "id": "collectionId",
      "name": "Product Photos",
      "organizationId": "orgId333"
    }
  }
}

Response Fields

Media Object

Field	Type	Description
`id`	string	UUID without hyphens
`name`	string	File name
`type`	string	`"image"`, `"video"`, or `"folder"`
`blob`	string	Public URL to the file
`path`	string	ltree folder path
`datasetId`	string	Parent collection ID
`width` / `height`	integer	Dimensions in pixels
`duration`	number \| null	Video duration in seconds
`sizeBytes`	integer	File size in bytes
`createdAt` / `updatedAt`	string	ISO 8601 timestamps
`sourceMediaId`	string \| null	ID of the original if this is a derived version
`versionNumber`	integer	Version number (1 for originals)
`metadata`	object	Tags, moderation, and custom attributes
`frames`	Frame[]	Processed frames (1 for images, many for videos)
`dataset`	object	Parent collection info

Frame Object

Field	Type	Description
`id`	string	Frame ID
`timestamp`	string	Timestamp within the video (`"0"` for images)
`blob`	string	Processed frame URL
`captions`	Caption[]	AI-generated descriptions
`objects`	Object[]	Detected objects with bounding boxes

Object

Field	Type	Description
`id`	string	Object ID — use with `similarToObjectId` in the browse endpoint
`type`	string	`object`, `face`, `frame`, `text`, etc.
`label`	string	Detected label
`blob`	string	URL to cropped object image (empty string if not available)

Error Responses

Status	Description
`401`	Missing or invalid authentication
`403`	No access to this media item's organization
`404`	Media not found
`500`	Internal server error

JavaScript Example

const media = await fetch(
  'https://lab.coreviz.io/api/media/MEDIA_ID',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
).then(r => r.json()).then(d => d.media);

console.log(media.blob);                           // public URL
console.log(media.metadata?.tags);                 // { color: ['red'], ... }
console.log(media.frames[0].objects.map(o => o.id)); // object IDs for similarity search

Get Media

On this page