Operations

File Metadata

Extract and write file metadata

Extract Metadata

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.

The metadata operation does not consume any conversion credits.

Task Parameters

operation

string required

Value is metadata.

input

string or array of task names required

The input task name(s) for this task.

input_format

string

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

Use a specific engine for the conversion.

engine_version

string

Use a specific engine version for the conversion.

timeout

integer

Timeout in seconds after the task will be cancelled. By default, tasks time out after 5 hours.

Example Job

Using the parameters from above, you can create a job:

POSThttps://api.cloudconvert.com/v2/jobs
{
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata",
            "input": "import-my-file"
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
}

# Install the CloudConvert CLI: npm install -g cloudconvert-cli
# The CloudConvert CLI does not support these task types: metadata.

$ curl -X POST "https://api.cloudconvert.com/v2/jobs" \
    -H "Authorization: Bearer API_KEY" \
    -H "Content-type: application/json" \
    -d '{
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata",
            "input": "import-my-file"
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
}'

use \CloudConvert\CloudConvert;
use \CloudConvert\Models\Job;
use \CloudConvert\Models\Task;

$cloudconvert = new CloudConvert(['api_key' => 'API_KEY']);

$job = (new Job())
   ->addTask(
       (new Task('import/url', 'import-my-file'))
         ->set('url', 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf')
     )
   ->addTask(
       (new Task('metadata', 'convert-my-file'))
         ->set('input', 'import-my-file')
     )
   ->addTask(
       (new Task('export/url', 'export-my-file'))
         ->set('input', 'convert-my-file')
     ); 

$cloudconvert->jobs()->create($job);

import CloudConvert from 'cloudconvert';

const cloudConvert = new CloudConvert('api_key');

let job = await cloudConvert.jobs.create({
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata",
            "input": "import-my-file"
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
});

import cloudconvert

cloudconvert.configure(api_key='API_KEY')

cloudconvert.Job.create(payload={
    'tasks': {
        'import-my-file': {
            'operation': 'import/url',
            'url': 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf'
        },
        'convert-my-file': {
            'operation': 'metadata',
            'input': 'import-my-file'
        },
        'export-my-file': {
            'operation': 'export/url',
            'input': 'convert-my-file'
        }
    }
})

Example Response

You can find an example result of of the metadata extraction of a PDF below:

{
  "data": {
    "id": "9a160154-58e2-437f-9b6b-19d63b1f59e3",
    "tag": "myjob-123",
    "status": "finished",
    "created_at": "2018-09-19T14:42:58+00:00",
    "started_at": "2018-09-19T14:42:58+00:00",
    "tasks": [
        {
    "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
      }
    }
  }
    ]
  }
}

Use the Job Builder to generate and try out metadata jobs.

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 below.

Possible metadata keys include Title, Author, Creator, Producer. You can find all possible properties in the exiftool documentation.

Task Parameters

operation

string required

Value is metadata/write.

input

string or array of task names required

The input task name(s) for this task.

input_format

string

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

Use a specific engine for the conversion.

engine_version

string

Use a specific engine version for the conversion.

metadata

dictionary required

Object of metadata to write.

filename

string

Choose a filename (including extension) for the output file.

timeout

integer

Timeout in seconds after the task will be cancelled. By default, tasks time out after 5 hours.

Example Job

Using the parameters from above, you can create a job:

POSThttps://api.cloudconvert.com/v2/jobs
{
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata/write",
            "input": "import-my-file",
            "metadata": {
                "Author": "Richard Hendricks",
                "Title": "The Pied Piper algorithm.",
                "Producer": "CloudConvert",
                "Creator": "CloudConvert"
            }
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
}

# Install the CloudConvert CLI: npm install -g cloudconvert-cli
# The CloudConvert CLI does not support these task types: metadata/write.

$ curl -X POST "https://api.cloudconvert.com/v2/jobs" \
    -H "Authorization: Bearer API_KEY" \
    -H "Content-type: application/json" \
    -d '{
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata/write",
            "input": "import-my-file",
            "metadata": {
                "Author": "Richard Hendricks",
                "Title": "The Pied Piper algorithm.",
                "Producer": "CloudConvert",
                "Creator": "CloudConvert"
            }
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
}'

use \CloudConvert\CloudConvert;
use \CloudConvert\Models\Job;
use \CloudConvert\Models\Task;

$cloudconvert = new CloudConvert(['api_key' => 'API_KEY']);

$job = (new Job())
   ->addTask(
       (new Task('import/url', 'import-my-file'))
         ->set('url', 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf')
     )
   ->addTask(
       (new Task('metadata/write', 'convert-my-file'))
         ->set('input', 'import-my-file')
         ->set('metadata', '[object Object]')
     )
   ->addTask(
       (new Task('export/url', 'export-my-file'))
         ->set('input', 'convert-my-file')
     ); 

$cloudconvert->jobs()->create($job);

import CloudConvert from 'cloudconvert';

const cloudConvert = new CloudConvert('api_key');

let job = await cloudConvert.jobs.create({
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "convert-my-file": {
            "operation": "metadata/write",
            "input": "import-my-file",
            "metadata": {
                "Author": "Richard Hendricks",
                "Title": "The Pied Piper algorithm.",
                "Producer": "CloudConvert",
                "Creator": "CloudConvert"
            }
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
});

import cloudconvert

cloudconvert.configure(api_key='API_KEY')

cloudconvert.Job.create(payload={
    'tasks': {
        'import-my-file': {
            'operation': 'import/url',
            'url': 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf'
        },
        'convert-my-file': {
            'operation': 'metadata/write',
            'input': 'import-my-file',
            'metadata': {
                'Author': 'Richard Hendricks',
                'Title': 'The Pied Piper algorithm.',
                'Producer': 'CloudConvert',
                'Creator': 'CloudConvert'
            }
        },
        'export-my-file': {
            'operation': 'export/url',
            'input': 'convert-my-file'
        }
    }
})

Use the Job Builder to generate and try out metadata/write jobs.

Create Archives

Create a task to create a ZIP, RAR, 7Z, TAR, TAR.GZ or TAR.BZ2 archive.

Execute Commands

Execute custom ffmpeg, imagemagick, and graphicsmagick commands.

File Metadata

Extract Metadata

Task Parameters

Example Job

Example Response

Write Metadata

Task Parameters

Example Job