Import or reserve a video

Authorizations

bearerAuth
apiKeyHeader

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-generated key for safe POST retries. The API retains the first JSON response for 24 hours. Reusing a key with another path or body returns 409 IDEMPOTENCY_REPLAY.

Example

import-launch-demo-20260901

Request Body^required

Source media, optional workspace destination, optional Studio folder, and post-import recipe.

application/json

object

source

required

One of: discriminator: type

object

type

required

Reserves server-authoritative object storage for a client upload.

string

Allowed value: upload

fileName

Upload display/object filename; defaults to upload.mp4. Path separators are rejected.

string

<= 255 characters

contentType

Upload MIME type; audio/* selects the audio ingest lane.

string

object

type

required

Provider that owns the URL:

youtube — a YouTube watch or share URL.
dropbox — a publicly accessible Dropbox share URL.
google_drive — a publicly accessible Google Drive share URL.

The value must match the provider represented by url.

string

Allowed values: youtube dropbox google_drive

url

required

Provider share or watch URL.

string format: uri

workspaceId

Destination workspace. Omit for the caller’s personal library.

string

>= 1 characters

folderId

Existing Studio folder id in the same library as the import. The video is added to that folder (UserVideos.tags). Create folders with POST /folders or in Studio.

string

>= 1 characters

products

Optional workflows staged after ingest.

object

dubs

Dub recipes grouped by product and target languages.

Array<object>

object

languages

required

Unique target languages to dub.

Array<string>

>= 1 items unique items

product

Voice product for every target language.

string

default: plus

Allowed values: plus premium

shorts

Shorts-family recipe staged after transcription.

object

kind

Output to generate after transcription: shorts creates short highlights, promo creates one 45–60 second promotional edit, and clips creates 5–25 minute landscape excerpts.

string

default: shorts

Allowed values: shorts promo clips

numClips

Number of outputs requested. The import parser rounds this value; shorts requests support 1–10, while clips execution clamps it to 1–4. Promo requests always create one output.

number

default: 3 >= 1 <= 10

minDuration

Minimum length of each shorts output in seconds. It must be no greater than maxDuration; promo and clips workflows use their own duration rules.

number

default: 15 >= 15 <= 180

maxDuration

Maximum length of each shorts output in seconds. It must be no less than minDuration; promo and clips workflows use their own duration rules.

number

default: 180 >= 15 <= 180

aspectRatio

Output frame shape: 9:16 is vertical, 16:9 is landscape, and 1:1 is square. Promos support 9:16 and 16:9; clips are always generated in 16:9.

string

default: 9:16

Allowed values: 9:16 16:9 1:1

captionStyle

Caption appearance. Valid values are default, karaoke, modern, impact, subtle, highlight, and pro_highlight; see their visual behavior in the Create shorts request.

string

default: default

Allowed values: default karaoke modern impact subtle highlight pro_highlight

clipSelectionPrompt

Natural-language guidance describing topics, speakers, or moments to prioritise when selecting clips.

string

<= 2000 characters

packaging

Metadata and thumbnail recipe staged after ingest.

object

title

Title generation settings; presence enables the job.

object

style

Tone used for the generated title:

funny — light, clever, or relatable framing.
scary — warning, risk, or mistake-to-avoid framing.
informational — direct benefit, how-to, or structured-value framing.
mysterious — curiosity-gap framing that withholds the payoff.
clickbait — bold, high-energy framing using authority or superlatives.

string

default: informational

Allowed values: funny scary informational mysterious clickbait

description

Description generation settings; presence enables the job.

object

type

Format used for generated copy:

youtube-description — an SEO-oriented YouTube description with chapters, hashtags, and tags.
social-post — a concise social post with a hook, takeaways, and hashtags.
how-to-guide — a step-by-step Markdown guide with timestamped instructions.
blog-post — a long-form Markdown article based on the video.
video-summary — a timestamped narrative summary with speaker attribution.

string

default: youtube-description

Allowed values: youtube-description social-post how-to-guide blog-post video-summary

thumbnail

Any of:

Faceless Creative zero-prompt (characterCount: 0).

boolean

Empty object — same as {enabled: true}.

object

0

object

enabled

required

Enables zero-prompt thumbnail generation.

boolean

characterCount

Number of character references to use.

integer

0 <= 3

characters

Character references matching characterCount.

Array<object>

<= 3 items

object

characterId

Saved character profile ID.

string

referenceImageIds

Saved reference image IDs.

Array<string>

<= 10 items

imageUrl

Primary character reference URL.

string format: uri

imageUrls

Additional character reference URLs.

Array<string>

<= 3 items

name

Character display name.

string

position

Desired composition position.

string

action

Desired character pose or action.

string

referenceSchemaVersion

Reference payload model. 1 uses the legacy aesthetic, layout, and design-influence interpretation. 2 separates style recreation from brand references and enables thumbnail-precision.

integer

default: 1

Allowed values: 1 2

pipelineMode

Thumbnail generation workflow. thumbnail-v2 supports character, style, and brand references. thumbnail-precision uses one or two content-plate references and does not accept character references.

string

default: thumbnail-v2

Allowed values: thumbnail-v2 thumbnail-precision

contentReferenceImageUrl

Primary content plate reference.

string format: uri

contentReferenceImageUrls

Precision-mode content plates.

Array<string>

designInfluenceImageUrl

Composition influence image.

string format: uri

styleReferenceImageUrl

Style influence image.

string format: uri

brandReferenceImageUrl

Brand influence image.

string format: uri

brandInfluence

Relative brand-style influence passed to generation.

number

autoDetectCharacters

Not available in precision mode.

boolean

characterDetectApprovalMode

Character detection workflow. auto accepts detected references and continues; review waits for approval before generation.

string

default: auto

Allowed values: auto review

autoDetectContentReferences

Precision only. When omitted and no content plate URLs are sent

boolean

contentSlotCount

Number of distinct content-plate references selected for precision mode. Use 1 for one reference frame or 2 for two complementary frames.

integer

default: 1

Allowed values: 1 2

contentDetectApprovalMode

Content-reference detection workflow. auto accepts detected frames and continues; review waits for approval before generation.

string

default: auto

Allowed values: auto review

contentDetectPrompt

Optional focus text that steers opaque key-moment detect.

string

textOverlay

Optional Precision headline burned into the thumbnail.

string

omitTextOverlay

When true

boolean

autoTranslateThumbnail

Effective only with non-empty thumbnailTranslationLanguageCodes.

boolean

thumbnailTranslationLanguageCodes

Languages for translated thumbnail variants.

Array<string>

unique items

brandVoiceId

Brand voice profile used by thumbnail copy.

string

<= 128 characters

Examples

Import and create a dub, shorts, and packaging

{
  "source": {
    "type": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "workspaceId": "ws_team_123",
  "products": {
    "dubs": [
      {
        "languages": [
          "es",
          "fr"
        ],
        "product": "plus"
      }
    ],
    "shorts": {
      "kind": "shorts",
      "numClips": 3,
      "aspectRatio": "9:16"
    },
    "packaging": {
      "title": {
        "style": "informational"
      },
      "description": {
        "type": "youtube-description"
      },
      "thumbnail": {
        "enabled": true,
        "pipelineMode": "thumbnail-v2",
        "characterCount": 1,
        "characters": [
          {
            "characterId": "char_01"
          }
        ],
        "brandVoiceId": "bv_01"
      }
    }
  }
}

Reserve an upload

{
  "source": {
    "type": "upload",
    "fileName": "launch-demo.mp4",
    "contentType": "video/mp4"
  }
}

Fetch HTTPS media into an existing Studio folder

{
  "source": {
    "type": "https",
    "url": "https://cdn.example.com/launch-demo.mp4"
  },
  "folderId": "fold_01JZ8M6A"
}

202

Video accepted. Poll the returned jobs; upload reservations also include upload instructions.

application/json

object

videoId

required

Created library video ID.

string

status

required

Initial import state.

string

Allowed values: queued processing ready failed

video

Imported video projection when immediately available.

object

id

required

Library video ID.

string

status

required

Overall normalized video processing state.

string

Allowed values: queued processing ready failed

title

Current video title.

string

description

Current video description.

string

duration

Media duration in seconds.

number

posterUrl

Current poster image URL.

string format: uri

provider

Internal source provider label.

string

mediaType

Ingested media kind.

string

Allowed values: video audio

defaultLanguageCode

Detected or selected source language.

string

>= 2 characters <= 16 characters /^[A-Za-z]{2,3}(?:-[A-Za-z]{2,4})?$/

url

Primary playback URL when available.

string format: uri

urlMulti

Playback URLs keyed by language code.

object

key

additional properties

string format: uri

workspaceId

Owning workspace, if any.

string

folderIds

Studio folder ids this video belongs to (UserVideos.tags).

Array<string>

createdAt

ISO creation timestamp.

string format: date-time

import

Import pipeline projection.

object

status

required

Current lifecycle state for this video subresource.

string

Allowed values: queued processing ready failed

language

Language represented by the subresource.

string

>= 2 characters <= 16 characters /^[A-Za-z]{2,3}(?:-[A-Za-z]{2,4})?$/

transcript

Source transcription projection.

object

status

required

Current lifecycle state for this video subresource.

string

Allowed values: queued processing ready failed

language

Language represented by the subresource.

string

>= 2 characters <= 16 characters /^[A-Za-z]{2,3}(?:-[A-Za-z]{2,4})?$/

upload

Upload reservation instructions returned only for upload sources.

object

objectPath

required

Server-authoritative destination object path.

string

complete

required

Relative route used to create the upload session.

string

jobs

required

Import, transcript, and recipe jobs to poll.

Array<object>

object

id

required

Deterministic, pollable job ID.

string

type

required

Product workflow represented by the job.

string

Allowed values: import transcript dub captions shorts thumbnail packaging download

status

required

Current normalized job lifecycle state.

string

Allowed values: queued processing ready failed

videoId

Parent video when applicable.

string

language

Target language for a dub or caption job.

string

>= 2 characters <= 16 characters /^[A-Za-z]{2,3}(?:-[A-Za-z]{2,4})?$/

product

Dubbing product used by a dub job.

string

default: plus

Allowed values: plus premium

automationType

Packaging automation when type is packaging.

string

Allowed values: generateTitle generateDescription zeroPromptThumbnail

result

Type-specific ready-state artifacts.

object

key

additional properties

any

error

Terminal failure details when status is failed.

object

code

required

Machine-readable job failure code.

string

message

required

Human-readable job failure explanation.

string

details

Type-specific identifiers and context.

object

key

additional properties

any

Examples

accepted

{
  "videoId": "vid_01JZ8M6A",
  "status": "queued",
  "jobs": [
    {
      "id": "import_vid_01JZ8M6A",
      "type": "import",
      "status": "queued"
    },
    {
      "id": "transcript_vid_01JZ8M6A",
      "type": "transcript",
      "status": "queued"
    }
  ]
}

400

Request fields are missing, malformed, out of bounds, or mutually inconsistent.

application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Example

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "The request contains invalid or missing fields.",
    "details": {}
  }
}

401

A supported authentication header is missing or contains an invalid Public API key.

application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Examples

Authentication header missing

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Missing API key.",
    "details": {}
  }
}

API key invalid

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key",
    "details": {}
  }
}

403

Authentication succeeded, but the required scope, workspace role, or resource permission is missing.

application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Examples

scope

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key lacks the required scope.",
    "details": {}
  }
}

404

The resource does not exist or is not accessible to the caller.

application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found.",
    "details": {}
  }
}

409

The source already exists, or the idempotency key was reused for a different request.

application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Example

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

422

The source provider is unsupported or its duration cannot be resolved.

application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Example

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

429

The account has insufficient credits, or the request exceeded a rate limit.

application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Example

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits.",
    "details": {
      "required": 60,
      "available": 20,
      "shortfall": 40
    }
  }
}

500

An unexpected server error occurred.

application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred.",
    "details": {}
  }
}

Import or reserve a video

Authorizations

Parameters

Header Parameters

Example

Request Body required

Examples

Responses

202

Examples

400

Example

401

Examples

403

Examples

404

Example

409

Example

422

Example

429

Example

500

Example

Request Body^required