Photos

Get Photo From Project

Request Sample

const result = await mediaviz.photos.getPhotoFromProject(
  '<TABLE_NAME>',
  '<PHOTO_ID>',
  {
    keywordListId: '<KEYWORD_LIST_ID>'
  }
);

import type { PhotoDisplay } from '@mediaviz/sdk';

const result: PhotoDisplay = await mediaviz.photos.getPhotoFromProject(
  '<TABLE_NAME>',
  '<PHOTO_ID>',
  {
    keywordListId: '<KEYWORD_LIST_ID>'
  }
);

const result = await mediaviz.photos.getPhotoFromProject(
  '<TABLE_NAME>',
  '<PHOTO_ID>',
  {
    keywordListId: '<KEYWORD_LIST_ID>'
  }
);

const { client } = useMediaViz();

const result = await client.photos.getPhotoFromProject(
  '<TABLE_NAME>',
  '<PHOTO_ID>',
  {
    keywordListId: '<KEYWORD_LIST_ID>'
  }
);

result = mediaviz.photos.get_photo_from_project(
    '<TABLE_NAME>',
    '<PHOTO_ID>',
    keyword_list_id='<KEYWORD_LIST_ID>'
)

$result = $mediaviz->photos->getPhotoFromProject(
  '<TABLE_NAME>',
  '<PHOTO_ID>',
  [
    'keywordListId' => '<KEYWORD_LIST_ID>'
  ]
);

curl -X GET 'https://api.mediaviz.ai/api/v1/photos/<TABLE_NAME>/<PHOTO_ID>' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo'

Response Sample

{
  "photo_s3_link": "https://example.com/...",
  "client_side_id": "string",
  "moment_id": 0,
  "file_path": "string",
  "image_metadata": {},
  "tags": [
    "string"
  ],
  "title": "string",
  "description": "string",
  "format": "string",
  "size": "string",
  "source_resolution_x": 0,
  "source_resolution_y": 0,
  "date_taken": "2025-01-15T10:30:00Z",
  "date_modified": "2025-01-15T10:30:00Z",
  "date_guessed": "2025-01-15T10:30:00Z",
  "date_uploaded": "2025-01-15T10:30:00Z",
  "latitude": 0.0,
  "longitude": 0.0,
  "country_code": "US",
  "country": "string",
  "state": "string",
  "city": "string",
  "average_hash": "string",
  "perceptual_hash": "string",
  "difference_hash": "string",
  "wavelet_hash_haar": "string",
  "color_hash": "string",
  "reference_1_average_distance": 0.0,
  "reference_2_average_distance": 0.0,
  "reference_3_average_distance": 0.0,
  "main_color_palette": [
    "<base64>"
  ],
  "color_averages": [
    "<base64>"
  ],
  "labels_from_classifications_model": {},
  "ocr_output": {},
  "bounding_boxes_from_faces_model": [
    {}
  ],
  "number_of_faces": 0,
  "blur_value": 0.0,
  "feature_extraction_output": [
    0.0
  ],
  "similar_photo_ids_high": [
    0
  ],
  "similar_photo_ids_medium": [
    0
  ],
  "similar_photo_ids_low": [
    0
  ],
  "evidence_score": 0.0,
  "face_score": 0.0,
  "content_score": 0.0,
  "aesthetic_score": 0.0,
  "similarity_set_ranking": 0,
  "topic": "string",
  "rank": 0,
  "hue_values": [
    0.0
  ],
  "light_values": [
    0.0
  ],
  "saturation_values": [
    0.0
  ],
  "user_id": 8507,
  "company_id": 1024,
  "id": 0,
  "project_table_name": "z-photos-1024-a1b2c3d4"
}

Get Photo Face Details From Project

Request Sample

const result = await mediaviz.photos.getPhotoFaceDetailsFromProject('<TABLE_NAME>', '<PHOTO_ID>');

import type { PhotoFace } from '@mediaviz/sdk';

const result: PhotoFace[] = await mediaviz.photos.getPhotoFaceDetailsFromProject('<TABLE_NAME>', '<PHOTO_ID>');

const result = await mediaviz.photos.getPhotoFaceDetailsFromProject('<TABLE_NAME>', '<PHOTO_ID>');

const { client } = useMediaViz();

const result = await client.photos.getPhotoFaceDetailsFromProject('<TABLE_NAME>', '<PHOTO_ID>');

result = mediaviz.photos.get_photo_face_details_from_project('<TABLE_NAME>', '<PHOTO_ID>')

$result = $mediaviz->photos->getPhotoFaceDetailsFromProject('<TABLE_NAME>', '<PHOTO_ID>');

curl -X GET 'https://api.mediaviz.ai/api/v1/photos/face_details/<TABLE_NAME>/<PHOTO_ID>' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo'

Response Sample

[
  {
    "smile_value": true,
    "smile_confidence": 0.0,
    "eyeglasses_value": true,
    "eyeglasses_confidence": 0.0,
    "sunglasses_value": true,
    "sunglasses_confidence": 0.0,
    "eyes_open_value": true,
    "eyes_open_confidence": 0.0,
    "emotion_happy_confidence": 0.0,
    "emotion_sad_confidence": 0.0,
    "landmark_eyeleft_x": 0.0,
    "landmark_eyeleft_y": 0.0,
    "landmark_eyeright_x": 0.0,
    "landmark_eyeright_y": 0.0,
    "landmark_mouthleft_x": 0.0,
    "landmark_mouthleft_y": 0.0,
    "landmark_mouthright_x": 0.0,
    "landmark_mouthright_y": 0.0,
    "landmark_nose_x": 0.0,
    "landmark_nose_y": 0.0,
    "pose_roll": 0.0,
    "pose_yaw": 0.0,
    "pose_pitch": 0.0,
    "quality_brightness": 0.0,
    "quality_sharpness": 0.0,
    "face_occluded_value": true,
    "eye_direction_yaw": 0.0,
    "eye_direction_pitch": 0.0,
    "eye_direction_confidence": 0.0
  }
]

Get Project Photo Ids By Table Name

Returns photo IDs sorted by date taken (asc, the default, returns the oldest first); photos without a date taken are ordered by photo ID. By default only the best photo from each group of similar photos is returned, plus any photo with no similar matches; pass include_all=true to return every photo. Filter with start_date and end_date (ISO 8601, e.g. 2024-01-01T00:00:00) or no_date_taken=true. include_all can't be combined with the date filters.

This endpoint is paginated and returns at most 5,000 items per request. Use the listed query parameters to page through the complete result set with keyset pagination.

Request Sample

const result = await mediaviz.photos.getProjectPhotoIdsByTableName(
  '<TABLE_NAME>',
  {
    ascOrDesc: '<ASC_OR_DESC>',
    lastId: '<LAST_ID>',
    limit: '<LIMIT>',
    includeAll: '<INCLUDE_ALL>',
    startDate: '<START_DATE>',
    endDate: '<END_DATE>',
    noDateTaken: '<NO_DATE_TAKEN>'
  }
);

const result = await mediaviz.photos.getProjectPhotoIdsByTableName(
  '<TABLE_NAME>',
  {
    ascOrDesc: '<ASC_OR_DESC>',
    lastId: '<LAST_ID>',
    limit: '<LIMIT>',
    includeAll: '<INCLUDE_ALL>',
    startDate: '<START_DATE>',
    endDate: '<END_DATE>',
    noDateTaken: '<NO_DATE_TAKEN>'
  }
);

const result = await mediaviz.photos.getProjectPhotoIdsByTableName(
  '<TABLE_NAME>',
  {
    ascOrDesc: '<ASC_OR_DESC>',
    lastId: '<LAST_ID>',
    limit: '<LIMIT>',
    includeAll: '<INCLUDE_ALL>',
    startDate: '<START_DATE>',
    endDate: '<END_DATE>',
    noDateTaken: '<NO_DATE_TAKEN>'
  }
);

const { client } = useMediaViz();

const result = await client.photos.getProjectPhotoIdsByTableName(
  '<TABLE_NAME>',
  {
    ascOrDesc: '<ASC_OR_DESC>',
    lastId: '<LAST_ID>',
    limit: '<LIMIT>',
    includeAll: '<INCLUDE_ALL>',
    startDate: '<START_DATE>',
    endDate: '<END_DATE>',
    noDateTaken: '<NO_DATE_TAKEN>'
  }
);

result = mediaviz.photos.get_project_photo_ids_by_table_name(
    '<TABLE_NAME>',
    asc_or_desc='<ASC_OR_DESC>',
    last_id='<LAST_ID>',
    limit='<LIMIT>',
    include_all='<INCLUDE_ALL>',
    start_date='<START_DATE>',
    end_date='<END_DATE>',
    no_date_taken='<NO_DATE_TAKEN>'
)

$result = $mediaviz->photos->getProjectPhotoIdsByTableName(
  '<TABLE_NAME>',
  [
    'ascOrDesc' => '<ASC_OR_DESC>',
    'lastId' => '<LAST_ID>',
    'limit' => '<LIMIT>',
    'includeAll' => '<INCLUDE_ALL>',
    'startDate' => '<START_DATE>',
    'endDate' => '<END_DATE>',
    'noDateTaken' => '<NO_DATE_TAKEN>'
  ]
);

curl -X GET 'https://api.mediaviz.ai/api/v1/photos/<TABLE_NAME>/' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo'

Response Sample

Get Ranked Project Photo Ids By Table Name

Returns photo IDs grouped into three tiers by overall quality: top_tier (top 15%), tier_2 (middle 70%), and tier_3 (bottom 15%). Only the best photo from each group of similar photos is included, and photos within each tier are ordered by date taken. When paging, pass the last photo ID from the last non-empty tier as last_id.

This endpoint is paginated and returns at most 5,000 items per request. Use the listed query parameters to page through the complete result set with keyset pagination.

Request Sample

const result = await mediaviz.photos.getRankedProjectPhotoIdsByTableName(
  '<TABLE_NAME>',
  {
    ascOrDesc: '<ASC_OR_DESC>',
    lastId: '<LAST_ID>',
    limit: '<LIMIT>',
    startDate: '<START_DATE>',
    endDate: '<END_DATE>',
    noDateTaken: '<NO_DATE_TAKEN>'
  }
);

const result = await mediaviz.photos.getRankedProjectPhotoIdsByTableName(
  '<TABLE_NAME>',
  {
    ascOrDesc: '<ASC_OR_DESC>',
    lastId: '<LAST_ID>',
    limit: '<LIMIT>',
    startDate: '<START_DATE>',
    endDate: '<END_DATE>',
    noDateTaken: '<NO_DATE_TAKEN>'
  }
);

const result = await mediaviz.photos.getRankedProjectPhotoIdsByTableName(
  '<TABLE_NAME>',
  {
    ascOrDesc: '<ASC_OR_DESC>',
    lastId: '<LAST_ID>',
    limit: '<LIMIT>',
    startDate: '<START_DATE>',
    endDate: '<END_DATE>',
    noDateTaken: '<NO_DATE_TAKEN>'
  }
);

const { client } = useMediaViz();

const result = await client.photos.getRankedProjectPhotoIdsByTableName(
  '<TABLE_NAME>',
  {
    ascOrDesc: '<ASC_OR_DESC>',
    lastId: '<LAST_ID>',
    limit: '<LIMIT>',
    startDate: '<START_DATE>',
    endDate: '<END_DATE>',
    noDateTaken: '<NO_DATE_TAKEN>'
  }
);

result = mediaviz.photos.get_ranked_project_photo_ids_by_table_name(
    '<TABLE_NAME>',
    asc_or_desc='<ASC_OR_DESC>',
    last_id='<LAST_ID>',
    limit='<LIMIT>',
    start_date='<START_DATE>',
    end_date='<END_DATE>',
    no_date_taken='<NO_DATE_TAKEN>'
)

$result = $mediaviz->photos->getRankedProjectPhotoIdsByTableName(
  '<TABLE_NAME>',
  [
    'ascOrDesc' => '<ASC_OR_DESC>',
    'lastId' => '<LAST_ID>',
    'limit' => '<LIMIT>',
    'startDate' => '<START_DATE>',
    'endDate' => '<END_DATE>',
    'noDateTaken' => '<NO_DATE_TAKEN>'
  ]
);

curl -X GET 'https://api.mediaviz.ai/api/v1/photos/ranked/<TABLE_NAME>/' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo'

Response Sample

{
  "top_tier": [
    1035601,
    1035602
  ],
  "tier_2": [
    1035603,
    1035604,
    1035605,
    1035606,
    1035607
  ],
  "tier_3": [
    1035608,
    1035609
  ]
}

Get Project Month Years With Photos

Returns a [year, month] pair for each month that has at least one photo with a date taken, in chronological order. To get the photos for a month, pass that month's range to getProjectPhotoIdsByTableName (or the ranked endpoint) as start_date and end_date, for example [2024, 3] becomes start_date=2024-03-01T00:00:00 and end_date=2024-03-31T23:59:59. Photos without a date taken aren't counted; use no_date_taken=true to retrieve them.

Request Sample

const result = await mediaviz.photos.getProjectMonthYearsWithPhotos('<TABLE_NAME>');

const result = await mediaviz.photos.getProjectMonthYearsWithPhotos('<TABLE_NAME>');

const result = await mediaviz.photos.getProjectMonthYearsWithPhotos('<TABLE_NAME>');

const { client } = useMediaViz();

const result = await client.photos.getProjectMonthYearsWithPhotos('<TABLE_NAME>');

result = mediaviz.photos.get_project_month_years_with_photos('<TABLE_NAME>')

$result = $mediaviz->photos->getProjectMonthYearsWithPhotos('<TABLE_NAME>');

curl -X GET 'https://api.mediaviz.ai/api/v1/photo_month_years/<TABLE_NAME>' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo'

Response Sample

Update Photo In Project

Request Sample

const result = await mediaviz.photos.updatePhotoInProject(
  {
    tableName: '<TABLE_NAME>',
    photoId: '<PHOTO_ID>',
    photoData: '<PHOTO_DATA>'
  }
);

import type { PhotoDisplay } from '@mediaviz/sdk';

const result: PhotoDisplay = await mediaviz.photos.updatePhotoInProject(
  {
    tableName: '<TABLE_NAME>',
    photoId: '<PHOTO_ID>',
    photoData: '<PHOTO_DATA>'
  }
);

const result = await mediaviz.photos.updatePhotoInProject(
  {
    tableName: '<TABLE_NAME>',
    photoId: '<PHOTO_ID>',
    photoData: '<PHOTO_DATA>'
  }
);

const { client } = useMediaViz();

const result = await client.photos.updatePhotoInProject(
  {
    tableName: '<TABLE_NAME>',
    photoId: '<PHOTO_ID>',
    photoData: '<PHOTO_DATA>'
  }
);

result = mediaviz.photos.update_photo_in_project(
    table_name='<TABLE_NAME>',
    photo_id='<PHOTO_ID>',
    photo_data='<PHOTO_DATA>'
)

$result = $mediaviz->photos->updatePhotoInProject(
  [
    'tableName' => '<TABLE_NAME>',
    'photoId' => '<PHOTO_ID>',
    'photoData' => '<PHOTO_DATA>'
  ]
);

curl -X PUT 'https://api.mediaviz.ai/api/v1/photos_update' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo'

Response Sample

{
  "photo_s3_link": "https://example.com/...",
  "client_side_id": "string",
  "moment_id": 0,
  "file_path": "string",
  "image_metadata": {},
  "tags": [
    "string"
  ],
  "title": "string",
  "description": "string",
  "format": "string",
  "size": "string",
  "source_resolution_x": 0,
  "source_resolution_y": 0,
  "date_taken": "2025-01-15T10:30:00Z",
  "date_modified": "2025-01-15T10:30:00Z",
  "date_guessed": "2025-01-15T10:30:00Z",
  "date_uploaded": "2025-01-15T10:30:00Z",
  "latitude": 0.0,
  "longitude": 0.0,
  "country_code": "US",
  "country": "string",
  "state": "string",
  "city": "string",
  "average_hash": "string",
  "perceptual_hash": "string",
  "difference_hash": "string",
  "wavelet_hash_haar": "string",
  "color_hash": "string",
  "reference_1_average_distance": 0.0,
  "reference_2_average_distance": 0.0,
  "reference_3_average_distance": 0.0,
  "main_color_palette": [
    "<base64>"
  ],
  "color_averages": [
    "<base64>"
  ],
  "labels_from_classifications_model": {},
  "ocr_output": {},
  "bounding_boxes_from_faces_model": [
    {}
  ],
  "number_of_faces": 0,
  "blur_value": 0.0,
  "feature_extraction_output": [
    0.0
  ],
  "similar_photo_ids_high": [
    0
  ],
  "similar_photo_ids_medium": [
    0
  ],
  "similar_photo_ids_low": [
    0
  ],
  "evidence_score": 0.0,
  "face_score": 0.0,
  "content_score": 0.0,
  "aesthetic_score": 0.0,
  "similarity_set_ranking": 0,
  "topic": "string",
  "rank": 0,
  "hue_values": [
    0.0
  ],
  "light_values": [
    0.0
  ],
  "saturation_values": [
    0.0
  ],
  "user_id": 8507,
  "company_id": 1024,
  "id": 0,
  "project_table_name": "z-photos-1024-a1b2c3d4"
}

Update Photo Ranking

Moves a photo to another tier. new_category must be top_tier, tier_2, or tier_3 (case-insensitive). Only photos that appear in the tiers can be moved, meaning the best photo of each similar group; moving a photo to the tier it's already in fails with 400.

Request Sample

const result = await mediaviz.photos.updatePhotoRanking('<TABLE_NAME>', '<PHOTO_ID>', '<NEW_CATEGORY>');

const result = await mediaviz.photos.updatePhotoRanking('<TABLE_NAME>', '<PHOTO_ID>', '<NEW_CATEGORY>');

const result = await mediaviz.photos.updatePhotoRanking('<TABLE_NAME>', '<PHOTO_ID>', '<NEW_CATEGORY>');

const { client } = useMediaViz();

const result = await client.photos.updatePhotoRanking('<TABLE_NAME>', '<PHOTO_ID>', '<NEW_CATEGORY>');

result = mediaviz.photos.update_photo_ranking('<TABLE_NAME>', '<PHOTO_ID>', '<NEW_CATEGORY>')

$result = $mediaviz->photos->updatePhotoRanking('<TABLE_NAME>', '<PHOTO_ID>', '<NEW_CATEGORY>');

curl -X PUT 'https://api.mediaviz.ai/api/v1/photos_update/<TABLE_NAME>/id/<PHOTO_ID>/rank/<NEW_CATEGORY>' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo'

Response Sample

{
  "ok": true
}

Delete Photo From Project

Deletes either a single photo or several photos from the same similar set in one call. The set is determined by the first ID in photo_ids; any other ID outside that set fails with 400 — This operation is only permitted within similar sets. To delete photos from different sets, make one call per set.

Request Sample

const result = await mediaviz.photos.deletePhotoFromProject(
  '<TABLE_NAME>',
  {
    photoIds: '<PHOTO_IDS>'
  }
);

const result = await mediaviz.photos.deletePhotoFromProject(
  '<TABLE_NAME>',
  {
    photoIds: '<PHOTO_IDS>'
  }
);

const result = await mediaviz.photos.deletePhotoFromProject(
  '<TABLE_NAME>',
  {
    photoIds: '<PHOTO_IDS>'
  }
);

const { client } = useMediaViz();

const result = await client.photos.deletePhotoFromProject(
  '<TABLE_NAME>',
  {
    photoIds: '<PHOTO_IDS>'
  }
);

result = mediaviz.photos.delete_photo_from_project('<TABLE_NAME>', photo_ids='<PHOTO_IDS>')

$result = $mediaviz->photos->deletePhotoFromProject(
  '<TABLE_NAME>',
  [
    'photoIds' => '<PHOTO_IDS>'
  ]
);

curl -X DELETE 'https://api.mediaviz.ai/api/v1/photos/<TABLE_NAME>/delete/' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo'

Response Sample

{
  "deletion of photos [1035601, 1035602]": true
}