UniPost
Dashboard

Create audio overlay

Creates an async media-processing job that combines one uploaded video with one uploaded audio file. Poll the job until it returns status: "succeeded", then publish output_media_id with POST/v1/posts.
GuideVideo + audio overlay
https://api.unipost.dev
POST/v1/media/audio-overlays
Authorization
In header · Bearer <token>
Optional header · string
Request Body
string
string

Authorization

AuthorizationBearer <token>In header
Workspace API key.
Idempotency-KeystringOptional header
Use the same key to replay the original job instead of creating duplicate processing work. A different request body with the same key returns idempotency_conflict.

Request Body

video_media_idstring
Uploaded video media ID from POST/v1/media. Must reference a video in the same workspace.
audio_media_idstring
Uploaded audio media ID from POST/v1/media. Audio files are processing inputs and cannot be published directly.
modeOptionalDefault: mixstring
How UniPost combines audio. Omit it to mix the uploaded audio with the video's original audio.
Valuesmix | replace
video_volumeOptionalDefault: 100number
Original video audio volume from 0 to 100. Used in mix mode.
audio_volumeOptionalDefault: 100number
Uploaded audio volume from 0 to 100.
audio_start_msOptionalDefault: 0number
Offset into the uploaded audio before mixing.
fitOptionalDefault: trim_to_videostring
How uploaded audio is fitted to the video duration.
Valuestrim_to_video | loop_to_video

Response Body

202
idstring
Audio overlay job ID.
statusstring
Current job state.
Valuesqueued | processing | succeeded | failed
video_media_idstring
Input video media ID.
audio_media_idstring
Input audio media ID.
output_media_idstring | null
Processed video media ID. Present only after the job succeeds.
modestring
Resolved audio mode.
fitstring
Resolved fit mode.
created_atstring
ISO timestamp when the job was created.
started_atstring | null
ISO timestamp when processing started.
completed_atstring | null
ISO timestamp when processing completed or failed.
errorobject | null
Processing failure details when status is failed.
200
idstring
Audio overlay job ID.
statusstring
Current job state.
Valuesqueued | processing | succeeded | failed
video_media_idstring
Input video media ID.
audio_media_idstring
Input audio media ID.
output_media_idstring | null
Processed video media ID. Present only after the job succeeds.
modestring
Resolved audio mode.
fitstring
Resolved fit mode.
created_atstring
ISO timestamp when the job was created.
started_atstring | null
ISO timestamp when processing started.
completed_atstring | null
ISO timestamp when processing completed or failed.
errorobject | null
Processing failure details when status is failed.
401
error.codestring
Usually "VALIDATION_ERROR", "IDEMPOTENCY_CONFLICT", "NOT_FOUND", or "INTERNAL_ERROR".
error.normalized_codestring
Lowercase alias such as "validation_error" or "idempotency_conflict".
error.issues[]array
Field-level validation details for invalid media IDs, unsupported mode or fit, invalid volume, or invalid audio offset.
request_idstring
Request identifier for debugging and support.
409
error.codestring
Usually "VALIDATION_ERROR", "IDEMPOTENCY_CONFLICT", "NOT_FOUND", or "INTERNAL_ERROR".
error.normalized_codestring
Lowercase alias such as "validation_error" or "idempotency_conflict".
error.issues[]array
Field-level validation details for invalid media IDs, unsupported mode or fit, invalid volume, or invalid audio offset.
request_idstring
Request identifier for debugging and support.
422
error.codestring
Usually "VALIDATION_ERROR", "IDEMPOTENCY_CONFLICT", "NOT_FOUND", or "INTERNAL_ERROR".
error.normalized_codestring
Lowercase alias such as "validation_error" or "idempotency_conflict".
error.issues[]array
Field-level validation details for invalid media IDs, unsupported mode or fit, invalid volume, or invalid audio offset.
request_idstring
Request identifier for debugging and support.
500
error.codestring
Usually "VALIDATION_ERROR", "IDEMPOTENCY_CONFLICT", "NOT_FOUND", or "INTERNAL_ERROR".
error.normalized_codestring
Lowercase alias such as "validation_error" or "idempotency_conflict".
error.issues[]array
Field-level validation details for invalid media IDs, unsupported mode or fit, invalid volume, or invalid audio offset.
request_idstring
Request identifier for debugging and support.
Use this endpoint for functionality, not platform music libraries. TikTok and Instagram API publishing do not let API clients attach arbitrary audio to image or carousel posts. UniPost creates a normal processed video instead, so the publish API receives a regular video media_id.