POST /v1/projects/:projectId/media/finalize

Promotes a completed upload into the project's media library, returning a stable assetId (a.k.a. mediaId) you can reference from influencers, content, and ad creative. Call this immediately after the signed PUT succeeds — unfinalized uploads are garbage-collected after 24 hours.

Finalize verifies the object exists (via HEAD), checks the declared size matches, and inserts the row. It is safe to call more than once with the same uploadId — the first call creates the row, subsequent calls return the same asset.

Example request

curl -X POST https://api.layers.com/v1/projects/{projectId}/media/finalize \
  -H "X-Api-Key: $LAYERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "uploadId": "upl_01HXA3KMNP4RSTUVWXYZABCDEF" }'

const res = await fetch(
  `https://api.layers.com/v1/projects/${projectId}/media/finalize`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.LAYERS_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ uploadId }),
  },
);
const asset = await res.json();

import os, httpx

r = httpx.post(
    f"https://api.layers.com/v1/projects/{project_id}/media/finalize",
    headers={
        "X-Api-Key": os.environ["LAYERS_API_KEY"],
        "Content-Type": "application/json",
    },
    json={"uploadId": upload_id},
)
asset = r.json()

Response

{
  "mediaId": "med_01HXA4MNP5RSTUVWXYZABCDEFGH",
  "assetId": "med_01HXA4MNP5RSTUVWXYZABCDEFGH",
  "url": "https://media.layers.com/.../founder-shot.jpg",
  "kind": "reference_image",
  "contentType": "image/jpeg",
  "mimeType": "image/jpeg",
  "byteSize": 482112,
  "sizeBytes": 482112,
  "filename": "founder-shot.jpg",
  "sha256": null,
  "checksumSha256": null,
  "createdAt": "2026-04-18T19:26:02Z"
}

Notes

• mediaId and assetId are aliases. Same uuid, two keys — use either. Newer code paths (influencer reference-images, content assets) accept both.
• contentType and mimeType are aliases. Same string, two keys.
• byteSize and sizeBytes are aliases. Same number.
• Re-finalize is a no-op. Calling finalize a second time with the same uploadId returns the existing row — use this for idempotent retries.

Errors

See also

• POST /v1/projects/:projectId/media/presign — step 1
• POST /v1/projects/:projectId/media — inline upload (bypasses presign + finalize)