> ## Documentation Index > Fetch the complete documentation index at: https://docs.melius.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a Ditto video ## OpenAPI ````yaml /api/openapi.json get /api/v1/ditto/{generationId} openapi: 3.0.2 info: title: Melius API version: '1' description: >- The Melius REST API. Authenticate with an API key as a bearer token (`Authorization: Bearer mel_...`) and select the team to act on with the `x-team-id` header. Generations run through the same node + run pipeline as the app: create a node on a canvas, start a run, poll the run, then read the resulting version asset. servers: - url: https://api.melius.com security: - apiKey: [] teamId: [] paths: /api/v1/ditto/{generationId}: get: tags: - ditto summary: Get a Ditto video operationId: ditto.get parameters: - in: path name: generationId schema: type: string format: uuid required: true responses: '200': description: '200' content: application/json: schema: type: object properties: generationId: type: string format: uuid status: type: string enum: - preparing - rendering - finalizing - ready - failed input: oneOf: - type: object properties: sourceAssetId: type: string format: uuid dittoTemplate: type: object properties: id: type: string format: uuid revision: type: integer minimum: 0 exclusiveMinimum: true required: - id - revision styleId: type: string format: uuid description: >- A Ditto style to re-render the whole source video in. Send no replacements with it. additionalInstructions: type: string maxLength: 2000 sourceRange: type: object properties: startMs: type: number minimum: 0 endMs: type: number minimum: 0 exclusiveMinimum: true required: - startMs - endMs modelId: type: string minLength: 1 maxLength: 100 resolution: type: string enum: - 480p - 720p - 1080p - 480P - 768P - 1080P audioMode: type: string enum: - original - mute default: original replacements: type: array items: type: object properties: referenceAssetId: type: string format: uuid description: >- Image asset showing the replacement appearance for this item. targetKind: type: string enum: - character - prop - background description: >- What this reference image replaces in the source video. targetDescription: type: string maxLength: 1000 description: >- Optional description identifying the existing character, prop or background to replace. pendingAvatarRenderId: type: string format: uuid description: >- A custom avatar render of this character that may still be in progress. The run waits a few minutes for it and uses its portrait in place of referenceAssetId if it finishes in time; otherwise it uses referenceAssetId. avatar: type: object properties: kind: type: string enum: - custom - curated description: >- custom for one of the team's Cast avatars; curated for a Melius avatar id: type: string format: uuid description: The avatar's id from GET /ditto/avatars. required: - kind - id description: >- The avatar whose image referenceAssetId is. Prepare takes it in place of referenceAssetId and returns both; run checks the avatar still has that image. required: - referenceAssetId - targetKind maxItems: 30 required: - sourceAssetId - audioMode - replacements - type: object properties: sourceAssetId: type: string format: uuid dittoTemplate: type: object properties: id: type: string format: uuid revision: type: integer minimum: 0 exclusiveMinimum: true required: - id - revision styleId: type: string format: uuid description: >- A Ditto style to re-render the whole source video in. Send no replacements with it. additionalInstructions: type: string maxLength: 2000 sourceRange: type: object properties: startMs: type: number minimum: 0 endMs: type: number minimum: 0 exclusiveMinimum: true required: - startMs - endMs modelId: type: string minLength: 1 maxLength: 100 resolution: type: string enum: - 480p - 720p - 1080p - 480P - 768P - 1080P audioMode: type: string enum: - original - mute default: original referenceAssetId: type: string format: uuid description: >- Image asset showing the replacement appearance for this item. targetKind: type: string enum: - character - prop - background description: >- What this reference image replaces in the source video. targetDescription: type: string maxLength: 1000 description: >- Optional description identifying the existing character, prop or background to replace. pendingAvatarRenderId: type: string format: uuid description: >- A custom avatar render of this character that may still be in progress. The run waits a few minutes for it and uses its portrait in place of referenceAssetId if it finishes in time; otherwise it uses referenceAssetId. required: - sourceAssetId - audioMode - referenceAssetId - targetKind canvasId: type: string format: uuid bulkNodeRunId: type: string format: uuid outputVersionId: type: string format: uuid outputAssetId: type: string format: uuid videoUrl: type: string nullable: true sourceVideoUrl: type: string nullable: true referenceImageUrl: type: string nullable: true references: type: array items: type: object properties: referenceAssetId: type: string format: uuid description: >- Image asset showing the replacement appearance for this item. targetKind: type: string enum: - character - prop - background description: >- What this reference image replaces in the source video. targetDescription: type: string maxLength: 1000 description: >- Optional description identifying the existing character, prop or background to replace. pendingAvatarRenderId: type: string format: uuid description: >- A custom avatar render of this character that may still be in progress. The run waits a few minutes for it and uses its portrait in place of referenceAssetId if it finishes in time; otherwise it uses referenceAssetId. avatar: type: object properties: kind: type: string enum: - custom - curated description: >- custom for one of the team's Cast avatars; curated for a Melius avatar id: type: string format: uuid description: The avatar's id from GET /ditto/avatars. required: - kind - id description: >- The avatar whose image referenceAssetId is. Prepare takes it in place of referenceAssetId and returns both; run checks the avatar still has that image. imageUrl: type: string nullable: true required: - referenceAssetId - targetKind - imageUrl canRetryFinalization: type: boolean retryQuoteId: type: string failureMessage: type: string gemsReturned: type: integer minimum: 0 exclusiveMinimum: true credits: type: object properties: charged: type: integer minimum: 0 refunded: type: integer minimum: 0 required: - charged - refunded failureReason: type: string enum: - insufficient_credits - content_policy - no_media_generated - provider_error - validation_error - timeout - system - unknown estimatedWait: type: object properties: lowSeconds: type: number minimum: 0 highSeconds: type: number minimum: 0 required: - lowSeconds - highSeconds retryOf: type: string format: uuid url: type: string required: - generationId - status - input - canvasId - sourceVideoUrl - referenceImageUrl - url '401': description: Missing, invalid, expired, or revoked API key. content: application/json: schema: type: object properties: statusCode: type: integer error: type: string message: type: string required: - statusCode - message '403': description: '403' content: application/json: schema: type: object properties: message: type: string required: - message '404': description: '404' content: application/json: schema: type: object properties: message: type: string required: - message '429': description: Rate limit reached — retry after the `Retry-After` header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: type: object properties: statusCode: type: integer error: type: string message: type: string retryAfterSeconds: type: integer required: - statusCode - message components: securitySchemes: apiKey: type: http scheme: bearer description: 'A Melius API key (`mel_...`), sent as `Authorization: Bearer `.' teamId: type: apiKey in: header name: x-team-id description: The team (workspace) to act on. Defaults to the key's team when omitted. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.