---
title: "Start a Ditto replacement"
method: POST
path: "/api/v1/ditto/replacements"
tags: ["ditto"]
---

# Start a Ditto replacement

`POST /api/v1/ditto/replacements`

## Request

- Base URL: `https://api.melius.com`
- URL: `https://api.melius.com/api/v1/ditto/replacements`
- Auth: HTTP bearer and API key in header `x-team-id`

## Request body

- object
  - `attemptId` string, uuid, required
  - `analytics` object
    - `visitId` string, uuid, required
    - `workId` string, uuid, required
    - `campaign` object
      - `source` string, required
      - `medium` 'email', required
      - `name` string, required
      - `content` string
      - `landedAt` string, date-time, required
    - `promo` object
      - `id` string, required
      - `surface` string, required
      - `clickedAt` string, date-time, required
      - `sessionId` string, uuid
  - `input` union, required
    - object
      - `sourceAssetId` string, uuid, required
      - `dittoTemplate` object
        - `id` string, uuid, required
        - `revision` integer, required
      - `additionalInstructions` string
      - `sourceRange` object
        - `startMs` number, required
        - `endMs` number, required
      - `modelId` string
      - `resolution` '480p' | '720p' | '1080p' | '480P' | '768P' | '1080P'
      - `audioMode` 'original' | 'mute'
      - `replacements` object[], required
        - `referenceAssetId` string, uuid, required: Image asset showing the replacement appearance for this item.
        - `targetKind` 'character' | 'prop' | 'background', required: What this reference image replaces in the source video.
        - `targetDescription` string: Optional description identifying the existing character, prop or background to replace.
    - object
      - `sourceAssetId` string, uuid, required
      - `dittoTemplate` object
        - `id` string, uuid, required
        - `revision` integer, required
      - `additionalInstructions` string
      - `sourceRange` object
        - `startMs` number, required
        - `endMs` number, required
      - `modelId` string
      - `resolution` '480p' | '720p' | '1080p' | '480P' | '768P' | '1080P'
      - `audioMode` 'original' | 'mute'
      - `referenceAssetId` string, uuid, required: Image asset showing the replacement appearance for this item.
      - `targetKind` 'character' | 'prop' | 'background', required: What this reference image replaces in the source video.
      - `targetDescription` string: Optional description identifying the existing character, prop or background to replace.
  - `retryFinalization` boolean
  - `quoteId` string, required
  - `maxCredits` number

## Response `200`

200

- object
  - `generationId` string, uuid, required
  - `status` 'preparing' | 'rendering' | 'finalizing' | 'ready' | 'failed', required
  - `input` union, required
    - object
      - `sourceAssetId` string, uuid, required
      - `dittoTemplate` object
        - `id` string, uuid, required
        - `revision` integer, required
      - `additionalInstructions` string
      - `sourceRange` object
        - `startMs` number, required
        - `endMs` number, required
      - `modelId` string
      - `resolution` '480p' | '720p' | '1080p' | '480P' | '768P' | '1080P'
      - `audioMode` 'original' | 'mute', required
      - `replacements` object[], required
        - `referenceAssetId` string, uuid, required: Image asset showing the replacement appearance for this item.
        - `targetKind` 'character' | 'prop' | 'background', required: What this reference image replaces in the source video.
        - `targetDescription` string: Optional description identifying the existing character, prop or background to replace.
    - object
      - `sourceAssetId` string, uuid, required
      - `dittoTemplate` object
        - `id` string, uuid, required
        - `revision` integer, required
      - `additionalInstructions` string
      - `sourceRange` object
        - `startMs` number, required
        - `endMs` number, required
      - `modelId` string
      - `resolution` '480p' | '720p' | '1080p' | '480P' | '768P' | '1080P'
      - `audioMode` 'original' | 'mute', required
      - `referenceAssetId` string, uuid, required: Image asset showing the replacement appearance for this item.
      - `targetKind` 'character' | 'prop' | 'background', required: What this reference image replaces in the source video.
      - `targetDescription` string: Optional description identifying the existing character, prop or background to replace.
  - `canvasId` string, uuid, required
  - `bulkNodeRunId` string, uuid
  - `outputVersionId` string, uuid
  - `outputAssetId` string, uuid
  - `videoUrl` string, nullable
  - `sourceVideoUrl` string, nullable, required
  - `referenceImageUrl` string, nullable, required
  - `references` object[]
    - `referenceAssetId` string, uuid, required: Image asset showing the replacement appearance for this item.
    - `targetKind` 'character' | 'prop' | 'background', required: What this reference image replaces in the source video.
    - `targetDescription` string: Optional description identifying the existing character, prop or background to replace.
    - `imageUrl` string, nullable, required
  - `canRetryFinalization` boolean
  - `retryQuoteId` string
  - `failureMessage` string
  - `failureReason` 'insufficient_credits' | 'content_policy' | 'no_media_generated' | 'provider_error' | 'validation_error' | 'timeout' | 'system' | 'unknown'
  - `estimatedWait` object
    - `lowSeconds` number, required
    - `highSeconds` number, required
  - `url` string, required

## Other responses

- `400`: 400
- `401`: Missing, invalid, expired, or revoked API key.
- `402`: 402
- `403`: 403
- `404`: 404
- `409`: 409
- `429`: Rate limit reached — retry after the `Retry-After` header.

## Changes

- **2026-11-03** `2a857511f605`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/melius/apis/melius-api/changes/api/v1/ditto/replacements/post.md)

---

[API](https://skmtc.dev/melius/apis/melius-api.md) - [All operations](https://skmtc.dev/melius/apis/melius-api/llms.txt) - [OpenAPI document](https://skmtc.dev/melius/apis/melius-api/revisions/2a857511f605?raw)