Basic SDK Usage

A complete guide to the MediaViz API — from creating your account to viewing AI-powered photo curation results.

Creating Your Account

Initialize the SDK Client

import { MediaViz } from '@mediaviz/sdk';

const mediaviz = new MediaViz({
  baseUrl: 'https://api.mediaviz.ai',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUri: 'http://localhost:3000/callback',
});

const { MediaViz } = require('@mediaviz/sdk');

const mediaviz = new MediaViz({
  baseUrl: 'https://api.mediaviz.ai',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUri: 'http://localhost:3000/callback',
});

require_once __DIR__ . '/vendor/autoload.php';

use MediaVizSdk\MediaVizClient;

$mediaviz = new MediaVizClient([
  'baseUrl'      => 'https://api.mediaviz.ai',
  'clientId'     => 'YOUR_CLIENT_ID',
  'clientSecret' => 'YOUR_CLIENT_SECRET',
  'redirectUri'  => 'http://localhost:3000/callback',
]);

Create the First Company User

To register a new company and its owner, call users.createUserAndCompany. This creates both the user and the associated company in a single call.

Required fields:

Name — the user's full name
Email — a valid email address (used for verification)
Password — account password
Account type — set to 3 for company owner
Company name — the name of your organization

A successful response triggers an email verification message to the provided address and returns a user_id and company_id. Record both — you will need them for subsequent requests.

Request Sample

const { user_id, company_id } = await mediaviz.users.createUserAndCompany(
  'Jane Smith',
  '[email protected]',
  3,
  's3cur3P@ss',
  null,
  null,
  null,
  'Acme Photography'
);

const { user_id, company_id } = await mediaviz.users.createUserAndCompany(
  'Jane Smith',
  '[email protected]',
  3,
  's3cur3P@ss',
  null,
  null,
  null,
  'Acme Photography'
);

$result = $mediaviz->users->createUserAndCompany(
  'Jane Smith',
  '[email protected]',
  3,
  's3cur3P@ss',
  null,
  null,
  null,
  'Acme Photography'
);
// $result['user_id'], $result['company_id']

curl -X POST 'https://api.mediaviz.ai/api/v1/users/new_company' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "Jane Smith",
  "email": "[email protected]",
  "company_id": null,
  "profile_picture": null,
  "payment_plan_type": null,
  "password": "s3cur3P@ss",
  "company_name": "Acme Photography"
}
JSON

Response Sample

{
  "user_id": "usr_01abc123",
  "company_id": "cmp_01xyz456",
  "email": "[email protected]",
  "message": "Verification email sent."
}

To add additional users to an existing company, use the same endpoint with account_type set to 1 (standard user) or 2 (company admin), and include the existing company_id.

Create Collection

A collection is a container for a set of photos that will be processed together by MediaViz AI models. Each collection is identified by a unique project_table_name in the format z-photos-{company_id}-{uuid}.

Collections are scoped to an outcome — the type of analysis you want performed. To create a collection, call project.create_project_and_run specifying the outcomes (e.g., curation) and the models to run. The response returns the project_table_name you will use for all subsequent operations on this collection.

Request Sample

const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Wedding Collection',
  null,
  null,
  'Wedding photos 2026',
  null,
  2,
  null,
  null,
  {
    outcomes: 'curation'
  }
);

const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Wedding Collection',
  null,
  null,
  'Wedding photos 2026',
  null,
  2,
  null,
  null,
  {
    outcomes: 'curation'
  }
);

$result = $mediaviz->projects->createProjectAndRun(
  'My Wedding Collection',
  null,
  null,
  'Wedding photos 2026',
  null,
  2,
  null,
  null,
  'curation'
);
// $result['project_table_name']

curl -X POST 'https://api.mediaviz.ai/api/v1/project_outcome/?outcomes=curation' \
  -H 'Authorization: Bearer mvz_sk_live_7K2wQ9pL3mR8xN4vBjH1cT6yF0dZaEuS' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "My Wedding Collection",
  "private": null,
  "type": null,
  "description": "Wedding photos 2026",
  "directory": null,
  "photo_upload_vector": 2,
  "thumbnail": null,
  "run_name": null
}
JSON

Response Sample

{
  "project_table_name": "z-photos-cmp_01xyz456-a1b2c3d4",
  "outcomes": ["curation"],
  "models": ["blur", "colors", "face_recognition", "image_classification", "similarity", "evidence"],
  "status": "created"
}

Upload Photo

Send each photo to the upload endpoint. Photos must be base64-encoded and resized to 256×256 px before upload. The SDK handles fetching the upload template for the collection automatically and caches it across calls.

Request Sample

const result = await mediaviz.photoUpload.uploadPhoto(
  'z-photos-cmp_01xyz456-a1b2c3d4',
  'cmp_01xyz456',
  'usr_01abc123',
  0,
  {
    title: 'IMG_0001.jpg',
    fileContent: '<base64-encoded image data>',
    mimetype: 'image/jpeg',
    filePath: '/photos/IMG_0001.jpg'
  }
);

const result = await mediaviz.photoUpload.uploadPhoto(
  'z-photos-cmp_01xyz456-a1b2c3d4',
  'cmp_01xyz456',
  'usr_01abc123',
  0,
  {
    title: 'IMG_0001.jpg',
    fileContent: '<base64-encoded image data>',
    mimetype: 'image/jpeg',
    filePath: '/photos/IMG_0001.jpg'
  }
);

$result = $mediaviz->photoUpload->uploadPhoto(
  'z-photos-cmp_01xyz456-a1b2c3d4',
  'cmp_01xyz456',
  'usr_01abc123',
  0,
  [
    'title' => 'IMG_0001.jpg',
    'file_content' => '<base64-encoded image data>',
    'mimetype' => 'image/jpeg',
    'file_path' => '/photos/IMG_0001.jpg'
  ]
);

curl -X POST 'https://api.mediaviz.ai/photo_upload' \
  -H 'Authorization: Bearer mvz_sk_live_7K2wQ9pL3mR8xN4vBjH1cT6yF0dZaEuS' \
  -H 'x-bucket-name: <BUCKET_NAME>' \
  -H 'x-photo-index: 0' \
  -H 'x-company-id: cmp_01xyz456' \
  -H 'x-user-id: usr_01abc123' \
  -H 'x-project-table-name: z-photos-cmp_01xyz456-a1b2c3d4' \
  -H 'x-title: <TITLE>' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "file_content": "<FILE_CONTENT>",
  "mimetype": "<MIMETYPE>",
  "file_path": "<FILE_PATH>"
}
JSON

Mark Photo Upload Complete

Once all photos have been uploaded, signal to MediaViz that the upload phase is finished. This triggers the AI processing pipeline to begin.

After this call, the collection transitions to a processing state and the models begin running.

Request Sample

const result = await mediaviz.projects.markProjectUploadComplete('z-photos-cmp_01xyz456-a1b2c3d4');

const result = await mediaviz.projects.markProjectUploadComplete('z-photos-cmp_01xyz456-a1b2c3d4');

$result = $mediaviz->projects->markProjectUploadComplete('z-photos-cmp_01xyz456-a1b2c3d4');

curl -X POST 'https://api.mediaviz.ai/api/v1/project/z-photos-cmp_01xyz456-a1b2c3d4/upload_complete/' \
  -H 'Authorization: Bearer mvz_sk_live_7K2wQ9pL3mR8xN4vBjH1cT6yF0dZaEuS'

Check Run Status

Poll for processing progress. The response includes an overall progress_percentage as well as individual status fields for each model that was configured for the collection.

Continue polling until progress_percentage reaches 100 and all model statuses indicate completion before fetching results.

Request Sample

const result = await mediaviz.projects.checkProjectStatus('z-photos-cmp_01xyz456-a1b2c3d4');

const result = await mediaviz.projects.checkProjectStatus('z-photos-cmp_01xyz456-a1b2c3d4');

$result = $mediaviz->projects->checkProjectStatus('z-photos-cmp_01xyz456-a1b2c3d4');

curl -X GET 'https://api.mediaviz.ai/api/v1/project/status/z-photos-cmp_01xyz456-a1b2c3d4' \
  -H 'Authorization: Bearer mvz_sk_live_7K2wQ9pL3mR8xN4vBjH1cT6yF0dZaEuS'

Response Sample

{
  "project_table_name": "z-photos-cmp_01xyz456-a1b2c3d4",
  "progress_percentage": 72,
  "models": {
    "blur": "complete",
    "colors": "complete",
    "face_recognition": "processing",
    "image_classification": "processing",
    "similarity": "pending",
    "evidence": "pending"
  }
}

Individual Photo Results

Retrieve detailed analysis for a single photo using photo.get_photo_from_project. The response includes the full set of model outputs for that photo, including:

blur_value — sharpness score
main_color_palette — dominant colors extracted from the image
labels_from_classifications_model — image classification tags
bounding_boxes_from_faces_model — detected face regions
similar_photo_ids_high / _medium / _low — similar photos grouped by similarity strength
evidence_score — overall curation score
face_score — quality score for face content
content_score — subject matter quality score
aesthetic_score — compositional and aesthetic quality score
similarity_set_ranking — rank within its similarity cluster

Request Sample

const result = await mediaviz.photos.getPhotoFromProject('z-photos-cmp_01xyz456-a1b2c3d4', 'ph_001');

const result = await mediaviz.photos.getPhotoFromProject('z-photos-cmp_01xyz456-a1b2c3d4', 'ph_001');

$result = $mediaviz->photos->getPhotoFromProject('z-photos-cmp_01xyz456-a1b2c3d4', 'ph_001');

curl -X GET 'https://api.mediaviz.ai/api/v1/photos/z-photos-cmp_01xyz456-a1b2c3d4/ph_001' \
  -H 'Authorization: Bearer mvz_sk_live_7K2wQ9pL3mR8xN4vBjH1cT6yF0dZaEuS'

Response Sample

{
  "photo_id": "ph_001",
  "blur_value": 0.95,
  "main_color_palette": ["#3a5a8c", "#f0e6d2", "#2c2c2c"],
  "labels_from_classifications_model": ["outdoor", "portrait", "natural light"],
  "bounding_boxes_from_faces_model": [
    { "x": 120, "y": 45, "width": 80, "height": 90 }
  ],
  "similar_photo_ids_high": ["ph_007"],
  "similar_photo_ids_medium": ["ph_012", "ph_019"],
  "similar_photo_ids_low": ["ph_031"],
  "evidence_score": 0.91,
  "face_score": 0.88,
  "content_score": 0.84,
  "aesthetic_score": 0.79,
  "similarity_set_ranking": 1
}