Convert GIF to MP4
Creates an asynchronous GIF-to-MP4 job. Poll
GET /v1/media/gif-conversions/{id}, then publish the successful output_media_id as a normal video with POST/v1/posts.Authorization
AuthorizationBearer <token>In header
Workspace API key.
Idempotency-KeystringOptional POST header
Replays the same normalized conversion without consuming another rolling fair-use unit. Reusing the key with different input returns idempotency_conflict.
Request Body
gif_media_idstring
An uploaded
image/gif Media ID from POST/v1/media. The actual stored object must belong to the current workspace and be 50 MB or smaller.background_colorOptionalDefault: #FFFFFFstring
Opaque six-digit #RRGGBB color used behind transparent pixels. UniPost normalizes it to uppercase.
Response Body
202
idstring
GIF conversion job ID.
kindstring
Valuesgif_to_mp4
statusstring
Current public job state.
Valuesqueued | processing | succeeded | failed
gif_media_idstring
Input GIF Media ID.
background_colorstring
Normalized opaque background color.
output_profilestring
Valuesuniversal_mp4_v1
output_media_idstring | null
Converted video Media ID. Present only after status is succeeded.
created_atstring
ISO timestamp when the job was created.
started_atstring | null
ISO timestamp when the worker first claimed the job.
completed_atstring | null
ISO timestamp when processing succeeded or failed.
errorobject | null
Stable code, customer-safe message, and retryable flag for a failed job.
404
error.codestring
Stable creation error such as media_not_found, gif_media_required, gif_size_exceeded, media_processing_capacity_exceeded, or gif_conversion_rate_limit_exceeded.
error.details.reset_atstring
Present for the rolling 24-hour conversion limit.
Retry-AfterintegerResponse header
Seconds before the caller should retry a 429 response.
request_idstring
Request identifier for support and diagnostics.
409
error.codestring
Stable creation error such as media_not_found, gif_media_required, gif_size_exceeded, media_processing_capacity_exceeded, or gif_conversion_rate_limit_exceeded.
error.details.reset_atstring
Present for the rolling 24-hour conversion limit.
Retry-AfterintegerResponse header
Seconds before the caller should retry a 429 response.
request_idstring
Request identifier for support and diagnostics.
422
error.codestring
Stable creation error such as media_not_found, gif_media_required, gif_size_exceeded, media_processing_capacity_exceeded, or gif_conversion_rate_limit_exceeded.
error.details.reset_atstring
Present for the rolling 24-hour conversion limit.
Retry-AfterintegerResponse header
Seconds before the caller should retry a 429 response.
request_idstring
Request identifier for support and diagnostics.
429
error.codestring
Stable creation error such as media_not_found, gif_media_required, gif_size_exceeded, media_processing_capacity_exceeded, or gif_conversion_rate_limit_exceeded.
error.details.reset_atstring
Present for the rolling 24-hour conversion limit.
Retry-AfterintegerResponse header
Seconds before the caller should retry a 429 response.
request_idstring
Request identifier for support and diagnostics.
503
error.codestring
Stable creation error such as media_not_found, gif_media_required, gif_size_exceeded, media_processing_capacity_exceeded, or gif_conversion_rate_limit_exceeded.
error.details.reset_atstring
Present for the rolling 24-hour conversion limit.
Retry-AfterintegerResponse header
Seconds before the caller should retry a 429 response.
request_idstring
Request identifier for support and diagnostics.
Conversion and publishing are separate operations. This endpoint never edits a draft or publishes automatically. X and Facebook can receive the original GIF directly; use the MP4 output for destinations that require video.
POST always returns 202 when a job is accepted, including an idempotent replay. GET returns 200 when the job can be read. Idempotency-Key applies only to POST.
Published UniPost SDK packages do not yet include GIF conversion helpers. Use the REST example on this page until updated SDK versions are released.
universal_mp4_v1 is H.264, yuv420p, constant 30 FPS, silent, fast-start MP4 with even dimensions and no upscaling above a 1920-pixel longest edge. Transparent pixels use the selected background color. Static GIFs and short animations produce at least five seconds of video; short animations repeat complete cycles.Input limits: 50 MB compressed, 4096 pixels per dimension, 2,000 frames, 1.5 billion decoded pixels, and a 60-second animation cycle. Processing has a five-minute processing limit, and the converted MP4 cannot exceed the global 4 GB Media limit.
The cURL example waits up to 15 minutes because queue time is separate from the five-minute server processing limit. A client timeout does not cancel the server-side job; keep the job ID and continue polling
GET /v1/media/gif-conversions/{id}.Terminal job codes include
gif_dimensions_exceeded, gif_frame_count_exceeded, gif_decode_budget_exceeded, gif_duration_exceeded, gif_probe_failed, gif_decode_failed, processing_timeout, output_size_exceeded, and gif_conversion_failed. Read error.retryable before deciding whether to submit a new job.Active Media Processing capacity is shared with Audio Overlay. New GIF jobs also have a Plan-based rolling 24-hour limit. Active inputs are protected from cleanup. After a successful conversion, UniPost retains both the input GIF and output MP4 for Free 1 day, API 2 days, Basic 4 days, Growth 15 days, and Team and Enterprise 30 days. After a failed conversion, no output Media exists; the input GIF is retained for Free 2 days, API 4 days, Basic 8 days, Growth 30 days, and Team and Enterprise 60 days. See GET/v1/media/:media_id for the shared Plan retention lifecycle.
Plan limits are active Media Processing jobs / new GIF conversions in a rolling 24-hour window: Free: 1 active / 10 GIF conversions; API: 2 / 50; Basic: 2 / 100; Growth: 4 / 300; Team: 6 / 1,000; Enterprise: 6 / 1,000 by default, with contract overrides available.