File Metadata

Extract Metadata

Job Builder

Create a task to extract metadata from files. Under the hood, this is using exiftool. You can use this operation to get the number of pages of PDFs or to get the resolution of images/videos. You can find an example result of of the metadata extraction of a PDF on the right.

The metadata operation does not consume any conversion credits.

Arguments
input string or array, required The ID of the input task for the conversion, normally the import task. Multiple task IDs can be provided as an array.
input_format string, optional The current format of the file, e.g. pdf. If not set, the extension of the input file is used as input format.
engine string, optional Use a specific engine for the conversion.

engine_version string, optional Use a specific engine version for the conversion.
timeout integer, optional Timeout in seconds after the task will be cancelled. By default, tasks time out after 5 hours.

Returns

The created task. You can find details about the task model response in the documentation about the show tasks endpoint.

Endpoint

POST https://api.cloudconvert.com/v2/metadata

Example Request

$ curl -X POST "https://api.cloudconvert.com/v2/metadata" \
       -H "Authorization: Bearer API_KEY" \
       -H "Content-type: application/json" \
       -d '{
  "input": "73df1e16-fd8b-47a1-a156-f197babde91a",
  "input_format": "pdf"
}'

Example Result

{
  "data": {
    "id": "c85f3ca9-164c-4e89-8ae2-c08192a7cb08",
    "operation": "metadata",
    "status": "finished",
    "message": null,
    "created_at": "2018-09-19T14:42:58+00:00",
    "started_at": "2018-09-19T14:42:58+00:00",
    "ended_at": "2018-09-19T14:42:58+00:00",
    "depends_on_tasks": {},
    "engine": "exiftool",
    "engine_version": "12.07",
    "payload": {
      "input": "73df1e16-fd8b-47a1-a156-f197babde91a",
      "input_format": "pdf"
    },
    "result": {
      "metadata": {
        "SourceFile": "zombies.pdf",
        "ExifToolVersion": 12.07,
        "FileName": "zombies.pdf",
        "Directory": ".",
        "FileSize": "169 kB",
        "FileModifyDate": "2020:08:18 14:04:31+00:00",
        "FileAccessDate": "2020:10:07 14:15:45+00:00",
        "FileInodeChangeDate": "2020:08:18 14:04:31+00:00",
        "FilePermissions": "rw-r--r--",
        "FileType": "PDF",
        "FileTypeExtension": "pdf",
        "MIMEType": "application/pdf",
        "PDFVersion": 1.4,
        "Linearized": "Yes",
        "Author": "Doug",
        "CreateDate": "2014:05:14 13:14:52-05:00",
        "ModifyDate": "2014:05:14 13:36:57-05:00",
        "XMPToolkit": "Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26        ",
        "Producer": "ScanSoft PDF Create! 7",
        "CreatorTool": "Microsoft Word - CONPLAN 8888-11 ... Pentagon Zombie Plan ... Counter Zombie Dominance 2011",
        "MetadataDate": "2014:05:14 13:36:57-05:00",
        "Format": "application/pdf",
        "Title": "Microsoft Word - CONPLAN 8888-11 ... Pentagon Zombie Plan ... Counter Zombie Dominance 2011",
        "Creator": "Doug",
        "DocumentID": "uuid:406c2972-c2bd-4470-95ad-1bfb6efb5258",
        "InstanceID": "uuid:c4d76637-aaa4-4e08-8a28-149644c2400c",
        "PageMode": "UseNone",
        "PageCount": 31
      }
    }
  }
}

Write Metadata

Job Builder

Create a task to write file metadata. Under the hood, this is using exiftool. You can use this operation to write any XMP or IPTC metadata, such as Author, Title, Copyright etc. You can find an example request to set PDF metadata on the right.

Arguments
input string or array, required The ID of the input task for the conversion, normally the import task. Multiple task IDs can be provided as an array.
input_format string, optional The current format of the file, e.g. pdf. If not set, the extension of the input file is used as input format.
metadata dictionary, required Keys and values of metadata to write. Possible keys include Title, Author, Creator, Producer. You can find all possible properties in the exiftool documentation.
filename string, optional Choose a filename (including extension) for the output file.
engine string, optional Use a specific engine for the conversion.

engine_version string, optional Use a specific engine version for the conversion.
timeout integer, optional Timeout in seconds after the task will be cancelled. By default, tasks time out after 5 hours.

Returns

The created task. You can find details about the task model response in the documentation about the show tasks endpoint.

Endpoint

POST https://api.cloudconvert.com/v2/metadata/write

Example Request

$ curl -X POST "https://api.cloudconvert.com/v2/metadata/write" \
       -H "Authorization: Bearer API_KEY" \
       -H "Content-type: application/json" \
       -d '{
  "input": "73df1e16-fd8b-47a1-a156-f197babde91a",
  "metadata": {
    "Author": "Richard Hendricks",
    "Title": "The Pied Piper algorithm.",
    "Producer": "CloudConvert",
    "Creator": "CloudConvert"
  },
  "filename": "output.pdf"
}'

Example Result

{
  "data": {
    "id": "c85f3ca9-164c-4e89-8ae2-c08192a7cb08",
    "operation": "metadata",
    "status": "finished",
    "message": null,
    "created_at": "2018-09-19T14:42:58+00:00",
    "started_at": "2018-09-19T14:42:58+00:00",
    "ended_at": "2018-09-19T14:42:58+00:00",
    "depends_on_tasks": {},
    "engine": "exiftool",
    "engine_version": "12.07",
    "payload": {
      "input": "73df1e16-fd8b-47a1-a156-f197babde91a",
      "input_format": "pdf"
    },
    "result": {
      "files": [
        {
          "filename": "output.pdf",
          "size": 398582
        }
      ]
    }
  }
}