Operations

AI

Describe what should happen with your files, and an AI model takes care of it.

AI operations let an AI model work on your files.

ai/agent tasks are currently in beta. Their behavior and the parameters and results described here may still change, and the agent can make mistakes.

AI Agent Beta

With an ai/agent task, you describe in plain language what should be done with your files. The agent then creates the required tasks inside the same job, step by step. To use it, create a job with an import task, an ai/agent task which uses it as input, and an export task which uses the ai/agent task as input.

The agent does not see the content of your files. It works with the prompt, the file names and the results of the tasks it has created, such as metadata. For example, it can extract the metadata of a file first, and decide based on the number of pages which conversions are needed. If a task fails, the agent tries to correct the cause. If it cannot, the ai/agent task fails.

The tasks created by the agent are regular tasks of the job. They are listed when showing the job and have their parent_task_id set to the ID of the ai/agent task. One ai/agent task can create up to 50 tasks.

The agent imports from and exports to the locations named in your prompt or in the other tasks of the job only, with the credentials given there. export/url tasks and exports to your connected cloud storages are always possible.

The engine of the task is the AI model. If it is not set, the default model is used.

ai/agent tasks are available within jobs only. The ai/agent task itself does not consume credits; the tasks created by the agent consume credits as usual.

AI can be turned off for your account or your team in the AI settings of the dashboard. Jobs with an ai/agent task are then rejected, and ai/agent tasks which are scheduled anyway, such as retries, fail with the code AI_DISABLED. AI_DISABLED is also used while AI is temporarily unavailable for all accounts. The same settings let you turn off the storage of your AI requests for improving our AI features.

Result

Tasks which use the ai/agent task as input, such as export tasks, get the output files of the tasks the agent has created. If the agent finishes without output files, for example because it answered a question, these tasks are cancelled with the code AGENT_NO_OUTPUT. Set ignore_error on the export task if this should not fail the job.

The message of the finished ai/agent task is a short summary by the agent. If you asked a question about your files, it is the answer. The result of the task contains:

output_tasks: the IDs of the tasks whose output files are the result.
steps: the steps the agent has taken.
suggestions: up to three follow-up requests the agent suggests, worded as a user would type them. They are set when the task has failed, too.

Example Prompts

Convert to PDF/A-2b.
Make this video smaller, at most 30 MB.
Convert all files to PDF and merge them into one PDF, in alphabetical order of the file names.
Create a PNG thumbnail of the first page with a width of 400 pixels.
Add the text "Confidential" as watermark to every page.
Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000.
Extract the ZIP archive and convert all images in it to WebP.
How many pages does this PDF have?

Task Parameters

operation

string required

Value is ai/agent.

input

string or array of task names

The input task name(s) for this task.

prompt

string required

What the agent should do with the input files. The agent creates the required tasks in this job.

engine

string

The AI model the agent uses. If not set, the default model is used.

timeout

integer

Timeout in seconds after the task will be cancelled.

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"
        },
        "agent": {
            "operation": "ai/agent",
            "input": "import-my-file",
            "prompt": "Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000."
        },
        "export-the-result": {
            "operation": "export/url",
            "input": "agent"
        }
    }
}

# Install the CloudConvert CLI: npm install -g cloudconvert-cli
$ cloudconvert ai/agent \
    --prompt='Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000.' \
    zombies.pdf

$ 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"
        },
        "agent": {
            "operation": "ai/agent",
            "input": "import-my-file",
            "prompt": "Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000."
        },
        "export-the-result": {
            "operation": "export/url",
            "input": "agent"
        }
    }
}'

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('ai/agent', 'agent'))
         ->set('input', 'import-my-file')
         ->set('prompt', 'Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000.')
     )
   ->addTask(
       (new Task('export/url', 'export-the-result'))
         ->set('input', 'agent')
     ); 

$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"
        },
        "agent": {
            "operation": "ai/agent",
            "input": "import-my-file",
            "prompt": "Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000."
        },
        "export-the-result": {
            "operation": "export/url",
            "input": "agent"
        }
    }
});

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'
        },
        'agent': {
            'operation': 'ai/agent',
            'input': 'import-my-file',
            'prompt': 'Convert the first page to PNG with a resolution of 2000x2000. If there are more pages, convert the pages after the first one to PNG with a maximum resolution of 1000x1000.'
        },
        'export-the-result': {
            'operation': 'export/url',
            'input': 'agent'
        }
    }
})

Use the Job Builder to generate and try out ai/agent jobs.

Execute Commands

Execute custom ffmpeg, imagemagick, and graphicsmagick commands.

Import Files

Import files to the CloudConvert service as input files for other operations