How to Enhance Digital Media Using the Digimarc Services API
19 January 2023
How to Use the Web API to Enhance Audio and Image Files
This article describes how to enhance a digital media file with a Digimarc digital watermark (known within the Web API as a service) through the Digimarc Services API. The process is the same for audio and image files, differing only in some details. This description assumes you have already uploaded the file to be enhanced. For a discussion of how to upload files, see Enhance Digital Media in the Digimarc Services API Overview.
NOTE: The HTTP headers for all the methods discussed here must include the Authorization header:
Authorization: <encodedCredentials> |
where <encodedCredentials> is your encoded Application Name and API Key. For more details on authorization, see the Overview of the Digimarc Services API [pdf].
Also, because a user can have access to multiple accounts, all requests must include the query parameter account=<account> to identify the account of interest.
Follow these steps to enhance a file through the Web API:
- Create a job using the
embed method.
- Headers (plus
Authorization): none - URL:
POST /embed/<fileId>/<serviceId>?account=<account> |
where:
<fileId> identifies the clean, or unmarked, file and<serviceId> identifies the Digimarc digital watermark (service) with which to enhance the file.<account> identifies the account.
You get the <fileId> when the file is uploaded. You get the <serviceId> by listing the services in your project with a call to the /services endpoint. - Status code on success:
- Response body on success:
where
<embedId> identifies the job. Save the <embedId> for use in the follow-up requests.
- Start the job.
-
- Headers (plus
Authorization): none - URL:
PUT /embed/<embedId>?account=<account> |
where
<embedId> identifies the embed job returned in the previous step.<account> identifies the account.
- Request body (for an image file):
{ "EmbedOptionsRequest": { "ImageOptions": { "WatermarkStrength": <DigimarcBarcodeStrength>, "PrintResolution": <printResolution>, "WatermarkResolution": <DigimarcBarcodeResolution> } } } |
where:
<DigimarcBarcodeStrength> is the strength of the Digimarc digital watermark (service) (optional, default 5),<printResolution> is the resolution (DPI) at which the image is to be printed (optional, default 300), and<DigimarcBarcodeResolution> is the resolution (WPI) of the digital watermark (service)(optional, default 75).
The request body can be omitted entirely, in which case the individual defaults apply. - Request body (for an audio file):
{ "EmbedOptionsRequest": { "AudioOptions": { "WatermarkStrength": <DigimarcBarcodeStrength> } } } |
where <DigimarcBarcodeStrength> is the strength of the digital watermark (service) (optional, default Medium).
The request body can be omitted entirely, in which case the individual default applies.
- Status code on success:
- Response body on success:
{ JobId: <embedId> ServiceId: <serviceId> EmbedStatus: "<embedStatus>" EmbedProgress: <embedProgress> UnmarkedFileId: "<fileId>" UnmarkedFileName: "<filename>" UnmarkedCreated: "<unmarkedCreatedDate>" MarkedFileId: "<markedFileId>" MarkedCreated: <markedCreatedDate> SubmitDate: "<submitDate>" CompletionDate: <completionDate> ResultCode: <resultCode> EmbedStatusToken: "<token>" } |
where:
<embedId> identifies the job from the previous step,<serviceId> identifies the Digimarc Barcode (service),<embedStatus> is an enumeration giving the status of the job,<embedProgress> is the percentage completion of the job (or null),<fileId> identifies the unmarked file,<filename> is the name of the unmarked file,<unmarkedCreatedDate> is the date of creation of the unmarked file,<markedFileId> identifies the marked file (or null)<markedCreatedDate> is the date of creation of the marked file (or null),<submitDate> is the date of submission of the job,<completionDate> is the date of completion of the job (or null),<resultCode> is an integer indicating the result of the job (or null), and<token> is the status token (a string of 9 digits).
All date fields are in ISO 8601 extended format. Values which can be null are null in this response body — they are updated as appropriate in the next step. Note the <token> for the next step.
- Check the status of the job. Enclose this request in a loop that continues until the job is complete. Completion is signaled when
<embedStatus> is EmbedComplete.
- Headers (plus
Authorization): none - URL:
GET /embed/<embedId>?token=<token>&timeout=<timeout>&account=<account> |
where:
<embedId> identifies the job used in the previous steps,<token> is the status token from the previous step or the last iteration of this step, and<timeout> is an integer from 1 to 30 showing the maximum time in seconds that the Web API server waits for a change in the job status before responding to this method.<account> identifies the account.
This method returns when the status of the job changes or the timeout is reached. - Status code on success:
- Response body on success:The response body resulting from checking the status of the job is the same JSON structure returned in the previous step with certain fields updated:
<embedStatus> is EmbedPreProcessing, EmbedInProgress, EmbedPostProcessing, or EmbedComplete.<embedProgress> is the percent completion of the job.<resultCode> is 0 if enhancing the file continues successfully, non-zero otherwise.<token> is the status token.
Until the <embedStatus> is EmbedComplete or the <resultCode> is non-zero, continue the loop with the latest <token> inserted into the URL. Check the interactive documentation of the Services API to see the errors indicated by a non-zero resultCode. On successful enhancement, the following fields are updated in the final response body:
<markedFileId> identifies the marked file.<markedCreatedDate> is the date of creation of the marked file.<completionDate> is the date of completion of enhancement.
On successful enhancement, the marked file (identified by <markedFileId>) can be downloaded for publication or broadcast.