Project Creation

Creating collections with outcomes and AI models in the MediaViz API.

Overview

Outcomes and Models

Collections are created via POST /api/v1/project_outcome/. You must specify at least one outcome or model as query parameters.

Outcomes are high-level analysis goals that automatically enable the required set of AI models. These enable complex processing, including running prerequisite models followed by summary analysis.

Models are individual AI capabilities — some can be requested directly, while others have prerequisites and must be requested through an outcome.

  • Outcomes — curation, similar_moments, high_similarity, near_duplicates, portraits, persons, normalize
  • Direct models — blur, colors, face_recognition, image_classification, image_comparison, image_describe, ocr

Curation

Curation

The curation outcome runs the full curation pipeline — identifying blurry images, extracting color data, recognizing faces, classifying image content, comparing images, and detecting similar and duplicate moments.

Request Sample

const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Curation Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'curation'
  }
);
import type { ProjectRunDisplay } from '@mediaviz/sdk';

const { project_table_name }: ProjectRunDisplay = await mediaviz.projects.createProjectAndRun(
  'My Curation Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'curation'
  }
);
const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Curation Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'curation'
  }
);
result = mediaviz.projects.create_project_and_run(
    'My Curation Collection',
    None,  # private — optional; defaults to false
    None,  # type — optional project type id
    None,  # description — optional
    None,  # directory — optional folder path
    None,  # photoUploadVector — optional
    None,  # thumbnail — optional cover image URL
    None,  # runName — optional label for this run
    outcomes='curation'
)
# result['project_table_name']
$result = $mediaviz->projects->createProjectAndRun(
  'My Curation Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  'curation'
);
// $result['project_table_name']
curl -X POST 'https://api.mediaviz.ai/api/v1/project_outcome/?outcomes=curation' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "My Curation Collection",
  "private": null,
  "type": null,
  "description": null,
  "directory": null,
  "photo_upload_vector": null,
  "thumbnail": null,
  "run_name": null
}
JSON

Similar Photo & Detection

Outcomes — similar_moments / high_similarity / near_duplicates / portraits

The similarity outcomes group images by visual likeness. Each variant applies a different sensitivity level that controls how closely images must match to be grouped.

  • similar_moments — low sensitivity; broadly groups related scenes
  • high_similarity — medium sensitivity; groups clearly similar images
  • near_duplicates — high sensitivity; groups near-identical shots
  • portraits — portrait-optimized sensitivity; designed for grouping headshots

Request Sample

const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Similarity Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'similar_moments'
  }
);
import type { ProjectRunDisplay } from '@mediaviz/sdk';

const { project_table_name }: ProjectRunDisplay = await mediaviz.projects.createProjectAndRun(
  'My Similarity Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'similar_moments'
  }
);
const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Similarity Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'similar_moments'
  }
);
result = mediaviz.projects.create_project_and_run(
    'My Similarity Collection',
    None,  # private — optional; defaults to false
    None,  # type — optional project type id
    None,  # description — optional
    None,  # directory — optional folder path
    None,  # photoUploadVector — optional
    None,  # thumbnail — optional cover image URL
    None,  # runName — optional label for this run
    outcomes='similar_moments'
)
# result['project_table_name']
$result = $mediaviz->projects->createProjectAndRun(
  'My Similarity Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  'similar_moments'
);
// $result['project_table_name']
curl -X POST 'https://api.mediaviz.ai/api/v1/project_outcome/?outcomes=similar_moments' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "My Similarity Collection",
  "private": null,
  "type": null,
  "description": null,
  "directory": null,
  "photo_upload_vector": null,
  "thumbnail": null,
  "run_name": null
}
JSON

Persons

Outcome — persons

The persons outcome detects and identifies human subjects across your collection.

Request Sample

const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Persons Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'persons'
  }
);
import type { ProjectRunDisplay } from '@mediaviz/sdk';

const { project_table_name }: ProjectRunDisplay = await mediaviz.projects.createProjectAndRun(
  'My Persons Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'persons'
  }
);
const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Persons Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'persons'
  }
);
result = mediaviz.projects.create_project_and_run(
    'My Persons Collection',
    None,  # private — optional; defaults to false
    None,  # type — optional project type id
    None,  # description — optional
    None,  # directory — optional folder path
    None,  # photoUploadVector — optional
    None,  # thumbnail — optional cover image URL
    None,  # runName — optional label for this run
    outcomes='persons'
)
# result['project_table_name']
$result = $mediaviz->projects->createProjectAndRun(
  'My Persons Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  'persons'
);
// $result['project_table_name']
curl -X POST 'https://api.mediaviz.ai/api/v1/project_outcome/?outcomes=persons' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "My Persons Collection",
  "private": null,
  "type": null,
  "description": null,
  "directory": null,
  "photo_upload_vector": null,
  "thumbnail": null,
  "run_name": null
}
JSON

Normalize

Outcome — normalize

The normalize outcome standardizes photo data in a collection for consistent downstream processing.

Request Sample

const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Normalize Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'normalize'
  }
);
import type { ProjectRunDisplay } from '@mediaviz/sdk';

const { project_table_name }: ProjectRunDisplay = await mediaviz.projects.createProjectAndRun(
  'My Normalize Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'normalize'
  }
);
const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Normalize Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    outcomes: 'normalize'
  }
);
result = mediaviz.projects.create_project_and_run(
    'My Normalize Collection',
    None,  # private — optional; defaults to false
    None,  # type — optional project type id
    None,  # description — optional
    None,  # directory — optional folder path
    None,  # photoUploadVector — optional
    None,  # thumbnail — optional cover image URL
    None,  # runName — optional label for this run
    outcomes='normalize'
)
# result['project_table_name']
$result = $mediaviz->projects->createProjectAndRun(
  'My Normalize Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  'normalize'
);
// $result['project_table_name']
curl -X POST 'https://api.mediaviz.ai/api/v1/project_outcome/?outcomes=normalize' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "My Normalize Collection",
  "private": null,
  "type": null,
  "description": null,
  "directory": null,
  "photo_upload_vector": null,
  "thumbnail": null,
  "run_name": null
}
JSON

Standalone Models

Direct Models

Any standalone models can be requested directly via the models query parameter and are not enabled by any outcome. See examples below.

Image Classification

Applies labels with confidence values to all photos in the collection. Enables custom album generation, natural-language search, and other metadata-driven processing.

Request Sample

const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Captions Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    models: 'image_classification'
  }
);
import type { ProjectRunDisplay } from '@mediaviz/sdk';

const { project_table_name }: ProjectRunDisplay = await mediaviz.projects.createProjectAndRun(
  'My Captions Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    models: 'image_classification'
  }
);
const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Captions Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    models: 'image_classification'
  }
);
result = mediaviz.projects.create_project_and_run(
    'My Captions Collection',
    None,  # private — optional; defaults to false
    None,  # type — optional project type id
    None,  # description — optional
    None,  # directory — optional folder path
    None,  # photoUploadVector — optional
    None,  # thumbnail — optional cover image URL
    None,  # runName — optional label for this run
    models='image_classification'
)
# result['project_table_name']
$result = $mediaviz->projects->createProjectAndRun(
  'My Labeled Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  'image_classification'
);
// $result['project_table_name']
curl -X POST 'https://api.mediaviz.ai/api/v1/project_outcome/?models=image_classification' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "My Captions Collection",
  "private": null,
  "type": null,
  "description": null,
  "directory": null,
  "photo_upload_vector": null,
  "thumbnail": null,
  "run_name": null
}
JSON

Captions

Generates a natural-language caption describing the content of each photo. Aliases: caption, describe, description.

Request Sample

const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Captions Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    models: 'image_describe'
  }
);
import type { ProjectRunDisplay } from '@mediaviz/sdk';

const { project_table_name }: ProjectRunDisplay = await mediaviz.projects.createProjectAndRun(
  'My Captions Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    models: 'image_describe'
  }
);
const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My Captions Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    models: 'image_describe'
  }
);
result = mediaviz.projects.create_project_and_run(
    'My Captions Collection',
    None,  # private — optional; defaults to false
    None,  # type — optional project type id
    None,  # description — optional
    None,  # directory — optional folder path
    None,  # photoUploadVector — optional
    None,  # thumbnail — optional cover image URL
    None,  # runName — optional label for this run
    models='image_describe'
)
# result['project_table_name']
$result = $mediaviz->projects->createProjectAndRun(
  'My Captions Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  'image_describe'
);
// $result['project_table_name']
curl -X POST 'https://api.mediaviz.ai/api/v1/project_outcome/?models=image_describe' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "My Captions Collection",
  "private": null,
  "type": null,
  "description": null,
  "directory": null,
  "photo_upload_vector": null,
  "thumbnail": null,
  "run_name": null
}
JSON

OCR (Optical Content Recognition)

Extracts text content from images using optical character recognition. Alias: optical_content_recognition.

Request Sample

const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My OCR Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    models: 'ocr'
  }
);
import type { ProjectRunDisplay } from '@mediaviz/sdk';

const { project_table_name }: ProjectRunDisplay = await mediaviz.projects.createProjectAndRun(
  'My OCR Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    models: 'ocr'
  }
);
const { project_table_name } = await mediaviz.projects.createProjectAndRun(
  'My OCR Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  {
    models: 'ocr'
  }
);
result = mediaviz.projects.create_project_and_run(
    'My OCR Collection',
    None,  # private — optional; defaults to false
    None,  # type — optional project type id
    None,  # description — optional
    None,  # directory — optional folder path
    None,  # photoUploadVector — optional
    None,  # thumbnail — optional cover image URL
    None,  # runName — optional label for this run
    models='ocr'
)
# result['project_table_name']
$result = $mediaviz->projects->createProjectAndRun(
  'My OCR Collection',
  null,  // private — optional; defaults to false
  null,  // type — optional project type id
  null,  // description — optional
  null,  // directory — optional folder path
  null,  // photoUploadVector — optional
  null,  // thumbnail — optional cover image URL
  null,  // runName — optional label for this run
  'ocr'
);
// $result['project_table_name']
curl -X POST 'https://api.mediaviz.ai/api/v1/project_outcome/?models=ocr' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "My OCR Collection",
  "private": null,
  "type": null,
  "description": null,
  "directory": null,
  "photo_upload_vector": null,
  "thumbnail": null,
  "run_name": null
}
JSON