Transform an asset

curl --request POST \
  --url https://api.zerogen.com/v1/assets/{assetId}/transform \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recipe": {
    "trim": {
      "startSeconds": 0,
      "endSeconds": 5
    },
    "resize": {
      "maxEdge": 1280
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({recipe: {trim: {startSeconds: 0, endSeconds: 5}, resize: {maxEdge: 1280}}})
};

fetch('https://api.zerogen.com/v1/assets/{assetId}/transform', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.zerogen.com/v1/assets/{assetId}/transform"

payload = { "recipe": {
        "trim": {
            "startSeconds": 0,
            "endSeconds": 5
        },
        "resize": { "maxEdge": 1280 }
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "projectId": "<string>",
  "model": "<string>",
  "modelVersion": "<string>",
  "status": "queued",
  "outputs": [
    {
      "index": 4503599627370495,
      "status": "queued",
      "asset": {
        "id": "<string>",
        "mimeType": "<string>",
        "width": 4503599627370495,
        "height": 4503599627370495,
        "durationMs": 4503599627370495,
        "preview": {
          "image96Url": "<string>",
          "image512Url": "<string>",
          "videoUrl": "<string>",
          "expiresAt": "2023-11-07T05:31:56Z"
        },
        "resourceUri": "<string>"
      },
      "error": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true,
        "param": "<string>",
        "details": {}
      },
      "warnings": [
        {
          "code": "<string>",
          "message": "<string>"
        }
      ],
      "draft": {
        "expiresAt": "2023-11-07T05:31:56Z",
        "upscalable": true,
        "upscale": "upscaling",
        "finalResolution": "<string>",
        "finalAssetId": "<string>"
      }
    }
  ],
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  },
  "billing": {
    "mode": "platform",
    "state": "held",
    "quotedMicroUsd": 4503599627370495,
    "heldMicroUsd": 4503599627370495,
    "chargedMicroUsd": 4503599627370495,
    "hold": {
      "state": "running",
      "endedAt": "2023-11-07T05:31:56Z"
    }
  },
  "createdBy": {
    "id": "<string>",
    "name": "<string>"
  },
  "createdVia": "web",
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "finishedAt": "2023-11-07T05:31:56Z",
  "webUrl": "<string>",
  "reused": true
}

{
  "id": "<string>",
  "projectId": "<string>",
  "model": "<string>",
  "modelVersion": "<string>",
  "status": "queued",
  "outputs": [
    {
      "index": 4503599627370495,
      "status": "queued",
      "asset": {
        "id": "<string>",
        "mimeType": "<string>",
        "width": 4503599627370495,
        "height": 4503599627370495,
        "durationMs": 4503599627370495,
        "preview": {
          "image96Url": "<string>",
          "image512Url": "<string>",
          "videoUrl": "<string>",
          "expiresAt": "2023-11-07T05:31:56Z"
        },
        "resourceUri": "<string>"
      },
      "error": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true,
        "param": "<string>",
        "details": {}
      },
      "warnings": [
        {
          "code": "<string>",
          "message": "<string>"
        }
      ],
      "draft": {
        "expiresAt": "2023-11-07T05:31:56Z",
        "upscalable": true,
        "upscale": "upscaling",
        "finalResolution": "<string>",
        "finalAssetId": "<string>"
      }
    }
  ],
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  },
  "billing": {
    "mode": "platform",
    "state": "held",
    "quotedMicroUsd": 4503599627370495,
    "heldMicroUsd": 4503599627370495,
    "chargedMicroUsd": 4503599627370495,
    "hold": {
      "state": "running",
      "endedAt": "2023-11-07T05:31:56Z"
    }
  },
  "createdBy": {
    "id": "<string>",
    "name": "<string>"
  },
  "createdVia": "web",
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "finishedAt": "2023-11-07T05:31:56Z",
  "webUrl": "<string>",
  "reused": true
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

Assets

Transform an asset

Makes a free Derived copy of an asset from a recipe: a frame from a video, or a cropped, resized or converted image, or a trimmed, cropped, despilled, LUT-graded, resized or converted video. The work runs in the background, so this returns a run; its output’s asset is the copy. It needs runs:read as well as runs:create, because it returns the run. Send Prefer: wait=N to hold the response until it ends. Your earlier run of the same recipe on this asset for the same destination returns with reused true instead of running again, unless it failed. New runs count toward the running caps. A test key can’t transform assets.

Needs the runs:create and runs:read scopes.

POST

assets

{assetId}

transform

Transform an asset

curl --request POST \
  --url https://api.zerogen.com/v1/assets/{assetId}/transform \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recipe": {
    "trim": {
      "startSeconds": 0,
      "endSeconds": 5
    },
    "resize": {
      "maxEdge": 1280
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({recipe: {trim: {startSeconds: 0, endSeconds: 5}, resize: {maxEdge: 1280}}})
};

fetch('https://api.zerogen.com/v1/assets/{assetId}/transform', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.zerogen.com/v1/assets/{assetId}/transform"

payload = { "recipe": {
        "trim": {
            "startSeconds": 0,
            "endSeconds": 5
        },
        "resize": { "maxEdge": 1280 }
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "projectId": "<string>",
  "model": "<string>",
  "modelVersion": "<string>",
  "status": "queued",
  "outputs": [
    {
      "index": 4503599627370495,
      "status": "queued",
      "asset": {
        "id": "<string>",
        "mimeType": "<string>",
        "width": 4503599627370495,
        "height": 4503599627370495,
        "durationMs": 4503599627370495,
        "preview": {
          "image96Url": "<string>",
          "image512Url": "<string>",
          "videoUrl": "<string>",
          "expiresAt": "2023-11-07T05:31:56Z"
        },
        "resourceUri": "<string>"
      },
      "error": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true,
        "param": "<string>",
        "details": {}
      },
      "warnings": [
        {
          "code": "<string>",
          "message": "<string>"
        }
      ],
      "draft": {
        "expiresAt": "2023-11-07T05:31:56Z",
        "upscalable": true,
        "upscale": "upscaling",
        "finalResolution": "<string>",
        "finalAssetId": "<string>"
      }
    }
  ],
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  },
  "billing": {
    "mode": "platform",
    "state": "held",
    "quotedMicroUsd": 4503599627370495,
    "heldMicroUsd": 4503599627370495,
    "chargedMicroUsd": 4503599627370495,
    "hold": {
      "state": "running",
      "endedAt": "2023-11-07T05:31:56Z"
    }
  },
  "createdBy": {
    "id": "<string>",
    "name": "<string>"
  },
  "createdVia": "web",
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "finishedAt": "2023-11-07T05:31:56Z",
  "webUrl": "<string>",
  "reused": true
}

{
  "id": "<string>",
  "projectId": "<string>",
  "model": "<string>",
  "modelVersion": "<string>",
  "status": "queued",
  "outputs": [
    {
      "index": 4503599627370495,
      "status": "queued",
      "asset": {
        "id": "<string>",
        "mimeType": "<string>",
        "width": 4503599627370495,
        "height": 4503599627370495,
        "durationMs": 4503599627370495,
        "preview": {
          "image96Url": "<string>",
          "image512Url": "<string>",
          "videoUrl": "<string>",
          "expiresAt": "2023-11-07T05:31:56Z"
        },
        "resourceUri": "<string>"
      },
      "error": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true,
        "param": "<string>",
        "details": {}
      },
      "warnings": [
        {
          "code": "<string>",
          "message": "<string>"
        }
      ],
      "draft": {
        "expiresAt": "2023-11-07T05:31:56Z",
        "upscalable": true,
        "upscale": "upscaling",
        "finalResolution": "<string>",
        "finalAssetId": "<string>"
      }
    }
  ],
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  },
  "billing": {
    "mode": "platform",
    "state": "held",
    "quotedMicroUsd": 4503599627370495,
    "heldMicroUsd": 4503599627370495,
    "chargedMicroUsd": 4503599627370495,
    "hold": {
      "state": "running",
      "endedAt": "2023-11-07T05:31:56Z"
    }
  },
  "createdBy": {
    "id": "<string>",
    "name": "<string>"
  },
  "createdVia": "web",
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "finishedAt": "2023-11-07T05:31:56Z",
  "webUrl": "<string>",
  "reused": true
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

A ZeroGen API key: zg_ for a live key, zg_test_ for a test key.

Headers

Idempotency-Key

string

Makes retries safe: a retry with the same key and body returns the first response for 24 hours instead of repeating the work. Reusing a key with a different body returns 409.

Required string length: 1 - 255

Pattern: ^[\x21-\x7e]+$

Prefer

string

wait=N holds the response up to N seconds (at most 60) until the run ends.

Pattern: ^wait=\d+$

Example:

"wait=30"

Path Parameters

assetId

string

required

The asset's ID

Body

application/json

recipe

object

required

Take one full-resolution frame from a video as a PNG.

Show child attributes

projectId

string

The project the copy goes into; the source asset's project when omitted

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

folderId

string | null

A folder in that project to also add the copy to; null or omitted for Unfiled

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response

The run has ended, within the requested wait, or had already ended.

string

required

projectId

string

required

The project that holds the outputs

model

string | null

required

Maximum string length: 200

Pattern: ^[a-z0-9]+(?:[.-][a-z0-9]+)*\/[a-z0-9]+(?:[.-][a-z0-9]+)*\/[a-z0-9]+(?:[.-][a-z0-9]+)*$

modelVersion

string | null

required

status

enum<string>

required

Available options:

queued,

running,

succeeded,

partial,

failed,

cancelled

outputs

object[]

required

Show child attributes

error

object | null

required

Show child attributes

billing

object

required

Show child attributes

createdBy

object | null

required

Who made it; null when ZeroGen recorded no one

Show child attributes

createdVia

enum<string> | null

required

Where it was made: web (the ZeroGen app), agent (ZeroGen's Agent), mcp (an MCP client) or api (an API key); null with createdBy

Available options:

web,

agent,

mcp,

api

createdAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

startedAt

string<date-time> | null

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

finishedAt

string<date-time> | null

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

webUrl

string | null

required

Opens Generate's review of the run's first ready output in ZeroGen, on your organization's host, after sign-in. null until an output is ready, and for test keys. It can change until the run ends

reused

boolean

required

True when this is your earlier run of the same recipe on this asset for the same destination, finished or in progress, so no new work started