Overview of Media Resources

Overview

Use media APIs to manage the files you plan to associate with resources such as brands, locations, and showcases. File size SHOULD NOT exceed 15 megabytes.

note

The photos and logos you receive can only be used on behalf of the applicable organization that shared access with you. You may not use the photos or logos outside of Apple Business or for other purposes, unless you have permission from the organization.

How Images Enter the System

There are two ways to provide an image file.

Upload is a synchronous operation. The file is validated inline during the POST request. If validation fails, the request returns 400 Bad Request with the rejection reason in the response body and no imageId is assigned. If validation passes, the response returns 201 Created with the assigned imageId.

Import is a two-phase operation:

1. Synchronous pre-validation — The service validates the request payload and URL before accepting the job. If pre-validation fails, the request returns 400 Bad Request with the rejection reason in the response body, and no imageId is assigned.
2. Asynchronous processing — If pre-validation passes, the service returns 202 Accepted with an imageId. The image is then downloaded and processed in the background. Use Get Metadata to poll the final state.

In both cases, if your request receives a 400, the rejection reason is in the response body — there is nothing to poll.

Model View