▶Vidmfy
Developer API

Automate the complete Vidmfy workflow with one professional API

Connect your website, application, CRM, e-commerce platform or internal workflow to Vidmfy. Create videos, follow production, inspect costs and retrieve cross-platform results without reproducing the video pipeline yourself.

Start creating →See how it works
✓

Built for production integrations

Versioned JSON endpoints, predictable status codes, pagination, filtering and stable video references.

✓

Protected against duplicate production

Every write request requires an idempotency key, preventing accidental repeated work and repeated billing.

✓

Controlled by your account

Create, scope, restrict, monitor and immediately revoke every API key from your connected Vidmfy account.

Built for practical production

One API above the complete video production pipeline

The Vidmfy API exposes the same protected business rules used by the web application: connected destination checks, provider selection, free-trial limits, wallet reservations, production status, publication retry logic and cost traceability.

A single integration can create a draft, select YouTube, Instagram, TikTok or Facebook destinations, queue production, follow every stage using the permanent VID reference, and retrieve publication links and analytics after completion.

API keys are shown once, stored only as one-way hashes and can be limited by permission, expiration, request rate and exact source IP addresses.

REST API v1

Endpoint reference

All responses are JSON. All authenticated routes require a scoped account API key.

https://vidmfy.com/api/v1
01

Authentication and headers

Use the complete secret only on a trusted server. Keys support granular scopes, expiration, rate limiting and an optional exact-IP allowlist.

Authorization: Bearer vfm_live_…
Accept: application/json
Content-Type: application/json
Idempotency-Key: order-1842-video-1
Idempotency is mandatory for writes. Repeating the same request and key within 24 hours returns the stored response. Reusing the key with a different payload returns HTTP 409.
↗

Open a GET request directly in your browser

For quick manual checks, read-only GET endpoints also accept the key in the query string.

https://vidmfy.com/api/v1/me?api_key=YOUR_API_KEY
Testing convenience only. A URL can remain in browser history, proxy logs or server access logs. Never use query-string authentication in a public link, screenshot or production integration. Prefer the Bearer header whenever possible.

Account & connections

Required scope: account:read / connections:read

GET/me

Account, plan, trial, wallet and current key information.

GET/capabilities

Supported providers, formats, statuses, languages and limits.

GET/connections

Connected publishing accounts and available content/video providers.

Videos

Required scope: videos:read / videos:write

GET/videos

List and filter videos by status, destination, campaign, date or search.

POST/videos

Create a draft or immediately queue a protected production.

GET/videos/{VID-reference}

Complete video, destination, publication and failure details.

PATCH/videos/{VID-reference}

Edit a video that has not started production.

DELETE/videos/{VID-reference}

Cancel an eligible video without removing its audit history.

GET/videos/{VID-reference}/status

Lightweight progress and destination status.

GET/videos/{VID-reference}/events

Ordered production and publication events.

GET/videos/{VID-reference}/costs

Wallet charges, API usage and refunds for one video.

GET/videos/{VID-reference}/analytics

Platform results attached to one video.

POST/videos/{VID-reference}/queue

Queue an existing draft after all preflight checks.

POST/videos/{VID-reference}/retry

Retry publication from the completed media when eligible.

Campaigns

Required scope: campaigns:read

GET/campaigns

Paginated campaigns with status and production counts.

GET/campaigns/{CMP-reference}

One campaign and its schedule configuration.

GET/campaigns/{CMP-reference}/videos

Videos produced or planned for the selected campaign.

Billing & analytics

Required scope: billing:read / analytics:read

GET/billing

Wallet balance, subscription and free-trial state.

GET/billing/transactions

Paginated wallet history with video references.

GET/analytics/summary

Consolidated publication and performance summary.

Source tools

Required scope: videos:write

POST/sources/url/check

Safely verify a public URL before using it as video content.

COMPLETE PARAMETERS & RESPONSES

Detailed documentation for every endpoint

Open an endpoint to see every accepted parameter, whether it is required, its location and type, an example value, and an example JSON response.

Service

GET/Discover API version, base URL, documentation and resources.+
Required scopePublicNo authentication required

Accepted parameters

No path, query or body parameter is accepted. Only the authentication header is required when the endpoint is not public.

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "name": "Vidmfy API",
        "version": "v1",
        "documentation": "https://vidmfy.com/?page=api-documentation",
        "base_url": "https://vidmfy.com/api/v1",
        "authentication": "Authorization: Bearer vfm_live_…",
        "resources": [
            "account",
            "connections",
            "videos",
            "campaigns",
            "billing",
            "analytics",
            "URL source checks"
        ]
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/healthCheck whether API v1 and its database bootstrap are operational.+
Required scopePublicNo authentication required

Accepted parameters

No path, query or body parameter is accepted. Only the authentication header is required when the endpoint is not public.

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "service": "Vidmfy API",
        "version": "v1",
        "status": "operational",
        "time": "2026-08-02T09:30:00+02:00"
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

Account

GET/meReturn the authenticated account, plan and current API key. Wallet data is included only with billing:read.+
Required scopeaccount:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

No path, query or body parameter is accepted. Only the authentication header is required when the endpoint is not public.

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "id": 42,
        "name": "Alex Martin",
        "email": "alex@example.com",
        "company": "Example Studio",
        "language": "English",
        "timezone": "Europe/Brussels",
        "plan": {
            "code": "creator",
            "subscription_status": "active"
        },
        "api_key": {
            "name": "Production website",
            "prefix": "vfm_live_9060E409",
            "scopes": [
                "account:read",
                "billing:read"
            ]
        },
        "wallet": {
            "balance_cents": 3595,
            "balance": "35.95"
        },
        "free_videos_remaining": 0
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/capabilitiesList supported providers, destinations, formats, languages, statuses and limits.+
Required scopeconnections:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

No path, query or body parameter is accepted. Only the authentication header is required when the endpoint is not public.

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "video_providers": [
            "auto",
            "heygen",
            "openai",
            "google",
            "runway"
        ],
        "video_types": [
            "short",
            "youtube"
        ],
        "aspect_ratios": [
            "9:16",
            "16:9",
            "1:1"
        ],
        "publishing_destinations": [
            "youtube",
            "instagram",
            "tiktok",
            "facebook"
        ],
        "statuses": [
            "draft",
            "queued",
            "generating_script",
            "generating_video",
            "published",
            "failed"
        ],
        "limits": {
            "page_size_max": 100,
            "api_key_rate_limit_max_per_minute": 300
        }
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/connectionsReturn safe provider availability and connected publishing destinations without secrets or OAuth tokens.+
Required scopeconnections:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

No path, query or body parameter is accepted. Only the authentication header is required when the endpoint is not public.

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "content_and_video_providers": {
            "openai": {
                "credential_source": "vidmfy",
                "ready": true,
                "managed_status": {
                    "available": true,
                    "enabled": true,
                    "unit": "tokens"
                }
            }
        },
        "publishing_destinations": {
            "youtube": [
                {
                    "id": 4,
                    "name": "Example Channel",
                    "youtube_channel_id": "UC123",
                    "is_default": true,
                    "last_verified_at": "2026-08-02 09:00:00"
                }
            ],
            "instagram": [
                {
                    "id": 12,
                    "name": "examplebrand",
                    "external_id": "17841400000000000",
                    "is_default": true,
                    "last_verified_at": "2026-08-02 09:00:00"
                }
            ]
        }
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

Videos

GET/videosList, search and filter videos.+
Required scopevideos:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
pageQueryinteger ≥ 1No

Page number. Default: 1.

1
per_pageQueryinteger · 1–100No

Number of results per page. Default: 25.

25
statusQuerycomma-separated enumNo

Filter by one or several production statuses.

published,failed
destinationQueryyoutube | instagram | tiktok | facebookNo

Return videos targeting this platform.

instagram
campaign_idQueryCMP referenceNo

Return videos linked to one campaign.

CMP-A1B2C3D4E5
fromQuerydate or ISO 8601No

Minimum publication date/time.

2026-08-01
toQuerydate or ISO 8601No

Maximum publication date/time.

2026-08-31T23:59:59+02:00
searchQuerystring · max 100No

Search reference, title or topic.

product

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": [
        {
            "id": "VID-A1B2C3D4E5",
            "title": "Discover our new product",
            "topic": "Present the main customer benefits",
            "status": "draft",
            "progress": {
                "stage": null,
                "validation": null,
                "error": null,
                "retry_count": 0
            },
            "format": {
                "type": "short",
                "aspect_ratio": "9:16",
                "duration_value": 1,
                "billing_duration_seconds": 60
            },
            "generation": {
                "provider": "auto",
                "model": null,
                "provider_job_id": null
            },
            "destinations": {
                "instagram": {
                    "enabled": true,
                    "account_id": 12,
                    "external_id": null,
                    "url": null
                }
            },
            "campaign_id": null,
            "scheduled_at": "2026-08-05T10:00:00+02:00",
            "publish_at": null,
            "published_at": null,
            "created_at": "2026-08-02T09:30:00+02:00",
            "updated_at": "2026-08-02T09:30:00+02:00"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 1,
        "pages": 1
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
POST/videosCreate a reviewable draft or queue a new protected production.+
Required scopevideos:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
Idempotency-KeyHeaderstring · 8–120Yes

Unique safe value for this write operation. Reusing it with the same payload replays the response.

order-1842-video-1
titleJSON bodystring · max 100Yes

Human-readable video title.

Discover our new product
topicJSON bodystring · max 10,000Yes

Subject, facts and instructions used to prepare the content.

Present the three main customer benefits
descriptionJSON bodystring · max 5,000No

Additional publication description.

A concise product presentation.
video_typeJSON bodyshort | youtubeNo

Video format. Default: short.

short
video_providerJSON bodyauto | heygen | openai | google | runwayNo

Generation provider. Auto selects a ready provider.

auto
provider_modelJSON bodystring · max 100No

Supported provider model override.

sora-2
heygen_generation_modeJSON bodyvideo_agent | avatarNo

HeyGen production mode.

video_agent
visual_instructionsJSON bodystring · max 10,000No

Scenes, rhythm, framing and visual direction.

Vertical product shots with clean transitions.
reference_media_urlsJSON bodyarray of HTTPS URLs · max 20No

Public media references accessible by the provider.

["https://example.com/product.jpg"]
duration_secondsJSON bodyintegerNo

Presenter: 1–1200. OpenAI, Veo and Runway: 4, 8 or 12.

60
languageJSON bodystring · max 80No

Content language. Defaults to account language.

English
toneJSON bodystring · max 120No

Editorial tone.

Professional and friendly
audienceJSON bodystring · max 2,000No

Target audience and useful context.

Small business owners
call_to_actionJSON bodystring · max 1,000No

Closing action requested from viewers.

Visit our website
aspect_ratioJSON body9:16 | 16:9 | 1:1No

Instagram, TikTok and Facebook Reels require 9:16.

9:16
visibilityJSON bodyprivate | unlisted | publicNo

YouTube visibility. Default: private.

private
thumbnail_promptJSON bodystring · max 2,000No

Optional YouTube thumbnail direction.

Bright product close-up
scheduled_atJSON bodyISO 8601 date-timeNo

Desired publication time with timezone. Defaults to now.

2026-08-05T10:00:00+02:00
modeJSON bodydraft | queueNo

Draft saves without production. Queue starts preflights and protected billing. Default: draft.

draft
destinationsJSON bodyobjectYes

At least one keyed destination object: youtube, instagram, tiktok or facebook.

{"instagram":{"enabled":true,"account_id":12}}
destinations.*.enabledJSON bodybooleanYes

Enables that destination.

true
destinations.*.account_idJSON bodyintegerNo

Connected account ID. Omit to use the default account.

12
destinations.tiktok.consentJSON bodybooleanRequired for TikTok queue

Confirms the TikTok publication choices.

true

Example response

HTTP 201 Created · application/json
{
    "ok": true,
    "data": {
        "id": "VID-A1B2C3D4E5",
        "title": "Discover our new product",
        "topic": "Present the main customer benefits",
        "status": "draft",
        "progress": {
            "stage": null,
            "validation": null,
            "error": null,
            "retry_count": 0
        },
        "format": {
            "type": "short",
            "aspect_ratio": "9:16",
            "duration_value": 1,
            "billing_duration_seconds": 60
        },
        "generation": {
            "provider": "auto",
            "model": null,
            "provider_job_id": null
        },
        "destinations": {
            "instagram": {
                "enabled": true,
                "account_id": 12,
                "external_id": null,
                "url": null
            }
        },
        "campaign_id": null,
        "scheduled_at": "2026-08-05T10:00:00+02:00",
        "publish_at": null,
        "published_at": null,
        "created_at": "2026-08-02T09:30:00+02:00",
        "updated_at": "2026-08-02T09:30:00+02:00"
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/videos/{video_id}Return complete content, generation, destination and publication details for one video.+
Required scopevideos:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
video_idPathstring · VID-XXXXXXXXXXYes

Permanent Vidmfy video reference.

VID-A1B2C3D4E5

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "id": "VID-A1B2C3D4E5",
        "title": "Discover our new product",
        "topic": "Present the main customer benefits",
        "status": "draft",
        "progress": {
            "stage": null,
            "validation": null,
            "error": null,
            "retry_count": 0
        },
        "format": {
            "type": "short",
            "aspect_ratio": "9:16",
            "duration_value": 1,
            "billing_duration_seconds": 60
        },
        "generation": {
            "provider": "auto",
            "model": null,
            "provider_job_id": null
        },
        "destinations": {
            "instagram": {
                "enabled": true,
                "account_id": 12,
                "external_id": null,
                "url": null
            }
        },
        "campaign_id": null,
        "scheduled_at": "2026-08-05T10:00:00+02:00",
        "publish_at": null,
        "published_at": null,
        "created_at": "2026-08-02T09:30:00+02:00",
        "updated_at": "2026-08-02T09:30:00+02:00",
        "content": {
            "description": "A concise product presentation.",
            "language": "English",
            "tone": "Professional and friendly",
            "audience": "Small business owners",
            "call_to_action": "Visit our website",
            "script": null,
            "visibility": "private"
        }
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
PATCH/videos/{video_id}Edit an existing draft or queued video. Only supplied fields are changed.+
Required scopevideos:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
video_idPathstring · VID-XXXXXXXXXXYes

Permanent Vidmfy video reference.

VID-A1B2C3D4E5
Idempotency-KeyHeaderstring · 8–120Yes

Unique safe value for this write operation. Reusing it with the same payload replays the response.

order-1842-video-1
titleJSON bodystring · max 100No

Human-readable video title.

Discover our new product
topicJSON bodystring · max 10,000No

Subject, facts and instructions used to prepare the content.

Present the three main customer benefits
descriptionJSON bodystring · max 5,000No

Additional publication description.

A concise product presentation.
video_typeJSON bodyshort | youtubeNo

Video format. Default: short.

short
video_providerJSON bodyauto | heygen | openai | google | runwayNo

Generation provider. Auto selects a ready provider.

auto
provider_modelJSON bodystring · max 100No

Supported provider model override.

sora-2
heygen_generation_modeJSON bodyvideo_agent | avatarNo

HeyGen production mode.

video_agent
visual_instructionsJSON bodystring · max 10,000No

Scenes, rhythm, framing and visual direction.

Vertical product shots with clean transitions.
reference_media_urlsJSON bodyarray of HTTPS URLs · max 20No

Public media references accessible by the provider.

["https://example.com/product.jpg"]
duration_secondsJSON bodyintegerNo

Presenter: 1–1200. OpenAI, Veo and Runway: 4, 8 or 12.

60
languageJSON bodystring · max 80No

Content language. Defaults to account language.

English
toneJSON bodystring · max 120No

Editorial tone.

Professional and friendly
audienceJSON bodystring · max 2,000No

Target audience and useful context.

Small business owners
call_to_actionJSON bodystring · max 1,000No

Closing action requested from viewers.

Visit our website
aspect_ratioJSON body9:16 | 16:9 | 1:1No

Instagram, TikTok and Facebook Reels require 9:16.

9:16
visibilityJSON bodyprivate | unlisted | publicNo

YouTube visibility. Default: private.

private
thumbnail_promptJSON bodystring · max 2,000No

Optional YouTube thumbnail direction.

Bright product close-up
scheduled_atJSON bodyISO 8601 date-timeNo

Desired publication time with timezone. Defaults to now.

2026-08-05T10:00:00+02:00
destinationsJSON bodyobjectNo

At least one keyed destination object: youtube, instagram, tiktok or facebook.

{"instagram":{"enabled":true,"account_id":12}}
destinations.*.enabledJSON bodybooleanNo

Required only inside a destination object supplied by the PATCH request.

true
destinations.*.account_idJSON bodyintegerNo

Connected account ID. Omit to use the default account.

12

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "id": "VID-A1B2C3D4E5",
        "title": "Updated product presentation",
        "topic": "Present the main customer benefits",
        "status": "draft",
        "progress": {
            "stage": null,
            "validation": null,
            "error": null,
            "retry_count": 0
        },
        "format": {
            "type": "short",
            "aspect_ratio": "9:16",
            "duration_value": 1,
            "billing_duration_seconds": 60
        },
        "generation": {
            "provider": "auto",
            "model": null,
            "provider_job_id": null
        },
        "destinations": {
            "instagram": {
                "enabled": true,
                "account_id": 12,
                "external_id": null,
                "url": null
            }
        },
        "campaign_id": null,
        "scheduled_at": "2026-08-05T10:00:00+02:00",
        "publish_at": null,
        "published_at": null,
        "created_at": "2026-08-02T09:30:00+02:00",
        "updated_at": "2026-08-02T09:30:00+02:00"
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
DELETE/videos/{video_id}Cancel an eligible draft or queued video while preserving its audit history.+
Required scopevideos:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
video_idPathstring · VID-XXXXXXXXXXYes

Permanent Vidmfy video reference.

VID-A1B2C3D4E5
Idempotency-KeyHeaderstring · 8–120Yes

Unique safe value for this write operation. Reusing it with the same payload replays the response.

order-1842-video-1

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "id": "VID-A1B2C3D4E5",
        "title": "Discover our new product",
        "topic": "Present the main customer benefits",
        "status": "cancelled",
        "progress": {
            "stage": null,
            "validation": null,
            "error": null,
            "retry_count": 0
        },
        "format": {
            "type": "short",
            "aspect_ratio": "9:16",
            "duration_value": 1,
            "billing_duration_seconds": 60
        },
        "generation": {
            "provider": "auto",
            "model": null,
            "provider_job_id": null
        },
        "destinations": {
            "instagram": {
                "enabled": true,
                "account_id": 12,
                "external_id": null,
                "url": null
            }
        },
        "campaign_id": null,
        "scheduled_at": "2026-08-05T10:00:00+02:00",
        "publish_at": null,
        "published_at": null,
        "created_at": "2026-08-02T09:30:00+02:00",
        "updated_at": "2026-08-02T09:30:00+02:00"
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/videos/{video_id}/statusRetrieve a lightweight production status suitable for polling.+
Required scopevideos:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
video_idPathstring · VID-XXXXXXXXXXYes

Permanent Vidmfy video reference.

VID-A1B2C3D4E5

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "id": "VID-A1B2C3D4E5",
        "status": "generating_video",
        "progress": {
            "stage": "video_generation",
            "validation": null,
            "error": null,
            "retry_count": 0
        },
        "destinations": {
            "instagram": {
                "enabled": true,
                "account_id": 12,
                "external_id": null,
                "url": null
            }
        },
        "updated_at": "2026-08-02T09:42:00+02:00"
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/videos/{video_id}/eventsReturn ordered activity and error events for production tracking.+
Required scopevideos:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
video_idPathstring · VID-XXXXXXXXXXYes

Permanent Vidmfy video reference.

VID-A1B2C3D4E5

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": [
        {
            "type": "activity",
            "status": "success",
            "message": "Script generation completed.",
            "process_name": null,
            "stage": null,
            "created_at": "2026-08-02 09:35:00"
        },
        {
            "type": "activity",
            "status": "info",
            "message": "Video generation started.",
            "process_name": null,
            "stage": null,
            "created_at": "2026-08-02 09:36:00"
        }
    ],
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/videos/{video_id}/costsReturn provider estimates, Vidmfy charges, reservations and refunds for one video.+
Required scopebilling:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
video_idPathstring · VID-XXXXXXXXXXYes

Permanent Vidmfy video reference.

VID-A1B2C3D4E5

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "video_id": "VID-A1B2C3D4E5",
        "currency": "USD",
        "totals": {
            "provider_cost_estimate_cents": 120.5,
            "customer_charge_cents": 185,
            "refunded_cents": 0,
            "net_customer_charge_cents": 185
        },
        "charges": [
            {
                "reference": "MAC-EXAMPLE",
                "provider": "heygen",
                "operation": "video_agent",
                "model": "video_agent",
                "credential_source": "vidmfy",
                "pricing_unit": "second",
                "actual_quantity": 55,
                "customer_charge_cents": 185,
                "refunded_cents": 0,
                "status": "finalized"
            }
        ]
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/videos/{video_id}/analyticsReturn daily platform metrics attached to one published video.+
Required scopeanalytics:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
video_idPathstring · VID-XXXXXXXXXXYes

Permanent Vidmfy video reference.

VID-A1B2C3D4E5

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "video_id": "VID-A1B2C3D4E5",
        "items": [
            {
                "platform": "instagram",
                "metric_date": "2026-08-02",
                "views": 1250,
                "reach": 980,
                "impressions": 1400,
                "likes": 84,
                "comments": 9,
                "shares": 17,
                "saves": 25,
                "watch_time_seconds": 22100,
                "average_watch_time_seconds": 17.68,
                "followers_gained": 12,
                "followers_lost": 0,
                "updated_at": "2026-08-02 10:00:00"
            }
        ]
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
POST/videos/{video_id}/queueStart an existing draft after capacity, destination, provider and billing preflights.+
Required scopevideos:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
video_idPathstring · VID-XXXXXXXXXXYes

Permanent Vidmfy video reference.

VID-A1B2C3D4E5
Idempotency-KeyHeaderstring · 8–120Yes

Unique safe value for this write operation. Reusing it with the same payload replays the response.

order-1842-video-1

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "id": "VID-A1B2C3D4E5",
        "title": "Discover our new product",
        "topic": "Present the main customer benefits",
        "status": "queued",
        "progress": {
            "stage": null,
            "validation": null,
            "error": null,
            "retry_count": 0
        },
        "format": {
            "type": "short",
            "aspect_ratio": "9:16",
            "duration_value": 1,
            "billing_duration_seconds": 60
        },
        "generation": {
            "provider": "auto",
            "model": null,
            "provider_job_id": null
        },
        "destinations": {
            "instagram": {
                "enabled": true,
                "account_id": 12,
                "external_id": null,
                "url": null
            }
        },
        "campaign_id": null,
        "scheduled_at": "2026-08-05T10:00:00+02:00",
        "publish_at": "2026-08-05T10:00:00+02:00",
        "published_at": null,
        "created_at": "2026-08-02T09:30:00+02:00",
        "updated_at": "2026-08-02T09:30:00+02:00"
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
POST/videos/{video_id}/retryRetry an eligible failure. Completed reusable media resumes at publication without regenerating the video.+
Required scopevideos:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
video_idPathstring · VID-XXXXXXXXXXYes

Permanent Vidmfy video reference.

VID-A1B2C3D4E5
Idempotency-KeyHeaderstring · 8–120Yes

Unique safe value for this write operation. Reusing it with the same payload replays the response.

order-1842-video-1

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "id": "VID-A1B2C3D4E5",
        "title": "Discover our new product",
        "topic": "Present the main customer benefits",
        "status": "ready_to_upload",
        "progress": {
            "stage": "publication_retry",
            "validation": null,
            "error": null,
            "retry_count": 1
        },
        "format": {
            "type": "short",
            "aspect_ratio": "9:16",
            "duration_value": 1,
            "billing_duration_seconds": 60
        },
        "generation": {
            "provider": "auto",
            "model": null,
            "provider_job_id": null
        },
        "destinations": {
            "instagram": {
                "enabled": true,
                "account_id": 12,
                "external_id": null,
                "url": null
            }
        },
        "campaign_id": null,
        "scheduled_at": "2026-08-05T10:00:00+02:00",
        "publish_at": null,
        "published_at": null,
        "created_at": "2026-08-02T09:30:00+02:00",
        "updated_at": "2026-08-02T09:30:00+02:00"
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

Campaigns

GET/campaignsList campaigns and their production counts.+
Required scopecampaigns:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
pageQueryinteger ≥ 1No

Page number. Default: 1.

1
per_pageQueryinteger · 1–100No

Number of results per page. Default: 25.

25

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": [
        {
            "id": "CMP-A1B2C3D4E5",
            "user_id": 42,
            "name": "August product launch",
            "campaign_type": "normal",
            "content_mode": "manual",
            "theme": "Present the new collection",
            "start_date": "2026-08-05",
            "end_date": "2026-08-31",
            "weekdays": [
                "1",
                "3",
                "5"
            ],
            "publish_time": "10:00:00",
            "language": "English",
            "destinations": "instagram,tiktok",
            "planned_videos": 12,
            "video_count": 12
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 1,
        "pages": 1
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/campaigns/{campaign_id}Return the selected campaign configuration and counts.+
Required scopecampaigns:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
campaign_idPathstring · CMP-XXXXXXXXXXYes

Permanent Vidmfy campaign reference.

CMP-A1B2C3D4E5

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "id": "CMP-A1B2C3D4E5",
        "name": "August product launch",
        "campaign_type": "normal",
        "content_mode": "manual",
        "theme": "Present the new collection",
        "start_date": "2026-08-05",
        "end_date": "2026-08-31",
        "weekdays": [
            "1",
            "3",
            "5"
        ],
        "publish_time": "10:00:00",
        "language": "English",
        "destinations": "instagram,tiktok",
        "planned_videos": 12,
        "video_count": 12
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/campaigns/{campaign_id}/videosList videos belonging to one campaign. Video list filters remain available.+
Required scopecampaigns:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
campaign_idPathstring · CMP-XXXXXXXXXXYes

Permanent Vidmfy campaign reference.

CMP-A1B2C3D4E5
pageQueryinteger ≥ 1No

Page number. Default: 1.

1
per_pageQueryinteger · 1–100No

Number of results per page. Default: 25.

25
statusQuerycomma-separated enumNo

Filter by one or several production statuses.

published,failed
destinationQueryyoutube | instagram | tiktok | facebookNo

Return videos targeting this platform.

instagram
fromQuerydate or ISO 8601No

Minimum publication date/time.

2026-08-01
toQuerydate or ISO 8601No

Maximum publication date/time.

2026-08-31T23:59:59+02:00
searchQuerystring · max 100No

Search reference, title or topic.

product

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": [
        {
            "id": "VID-A1B2C3D4E5",
            "title": "Discover our new product",
            "topic": "Present the main customer benefits",
            "status": "draft",
            "progress": {
                "stage": null,
                "validation": null,
                "error": null,
                "retry_count": 0
            },
            "format": {
                "type": "short",
                "aspect_ratio": "9:16",
                "duration_value": 1,
                "billing_duration_seconds": 60
            },
            "generation": {
                "provider": "auto",
                "model": null,
                "provider_job_id": null
            },
            "destinations": {
                "instagram": {
                    "enabled": true,
                    "account_id": 12,
                    "external_id": null,
                    "url": null
                }
            },
            "campaign_id": "CMP-A1B2C3D4E5",
            "scheduled_at": "2026-08-05T10:00:00+02:00",
            "publish_at": null,
            "published_at": null,
            "created_at": "2026-08-02T09:30:00+02:00",
            "updated_at": "2026-08-02T09:30:00+02:00"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 12,
        "pages": 1
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

Billing

GET/billingReturn wallet balance, subscription, production limits and free-video counter.+
Required scopebilling:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

No path, query or body parameter is accepted. Only the authentication header is required when the endpoint is not public.

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "currency": "USD",
        "wallet": {
            "balance_cents": 3595,
            "balance": "35.95"
        },
        "subscription": {
            "status": "active",
            "plan": "creator",
            "interval": "month",
            "current_period_end": "2026-09-01T00:00:00+02:00"
        },
        "limits": {
            "monthly_videos": 30,
            "used_this_month": 7
        },
        "free_videos_remaining": 0
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
GET/billing/transactionsReturn paginated wallet movements with video references when applicable.+
Required scopebilling:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
pageQueryinteger ≥ 1No

Page number. Default: 1.

1
per_pageQueryinteger · 1–100No

Number of results per page. Default: 25.

25

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": [
        {
            "id": 901,
            "type": "debit",
            "amount_cents": -185,
            "balance_after_cents": 3595,
            "description": "Vidmfy API · HeyGen · video agent",
            "created_at": "2026-08-02 09:36:00",
            "video_id": "VID-A1B2C3D4E5"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 1,
        "pages": 1
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

Analytics

GET/analytics/summaryReturn consolidated platform performance, top content and analytics connection state.+
Required scopeanalytics:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
limitQueryinteger · 1–50No

Maximum number of top-performing content items. Default: 12.

12

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "summary": {
            "platforms": {
                "youtube": {
                    "label": "YouTube",
                    "views": 4200,
                    "likes": 210
                },
                "instagram": {
                    "label": "Instagram",
                    "views": 7600,
                    "likes": 540
                }
            }
        },
        "top_content": [
            {
                "video_id": "VID-A1B2C3D4E5",
                "platform": "instagram",
                "title": "Discover our new product",
                "views": 1250,
                "permalink": "https://instagram.com/reel/example"
            }
        ],
        "connections": [
            {
                "platform": "instagram",
                "status": "connected",
                "last_success_at": "2026-08-02 09:55:00"
            }
        ]
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

Sources

POST/sources/url/checkVerify and safely extract a public web page before it is used as a content source.+
Required scopevideos:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample
Idempotency-KeyHeaderstring · 8–120Yes

Unique safe value for this write operation. Reusing it with the same payload replays the response.

order-1842-video-1
urlJSON bodypublic HTTP(S) URL · max 2,048Yes

Public URL to validate. Private, local, authenticated and unsafe hosts are blocked.

https://example.com/product

Example response

HTTP 200 OK · application/json
{
    "ok": true,
    "data": {
        "url": "https://example.com/product",
        "final_url": "https://example.com/product",
        "domain": "example.com",
        "title": "Example product",
        "description": "A practical product for small businesses.",
        "canonical_url": "https://example.com/product",
        "preview_image_url": "https://example.com/product.jpg",
        "word_count": 640,
        "content_hash": "d2a72e74b183f18c…",
        "headings": [
            "A better way to work",
            "Main benefits"
        ],
        "reference_media_urls": [
            "https://example.com/product.jpg"
        ]
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
02

Video request fields

The same payload is used to create a video and to edit a draft. Omitted optional values use safe account defaults.

FieldTypeRequiredDescription
titlestring · 100YesHuman-readable production title.
topicstring · 10,000YesSubject, facts and instructions used to prepare the content.
descriptionstring · 5,000NoAdditional publication description.
video_typeshort | youtubeNoDefaults to short.
video_providerauto | heygen | openai | google | runwayNoAuto selects a ready provider.
provider_modelstring · 100NoOptional supported model override.
duration_secondsintegerNoPresenter: 1–1200. Cinematic providers: 4, 8 or 12.
aspect_ratio9:16 | 16:9 | 1:1NoReels, TikTok and Facebook require 9:16.
languagestring · 80NoContent language. Defaults to the account language.
tonestring · 120NoEditorial tone for the script.
audiencestring · 2,000NoIntended audience and useful context.
call_to_actionstring · 1,000NoRequested closing action.
visibilityprivate | unlisted | publicNoYouTube visibility. Defaults to private.
thumbnail_promptstring · 2,000NoOptional thumbnail direction.
scheduled_atISO 8601 date-timeNoDesired publication time in an explicit timezone.
modedraft | queueNoDraft is the safe default; queue starts protected production.
destinationsobjectYesOne or more keyed objects: youtube, instagram, tiktok, facebook.
Destination object: use {"enabled": true, "account_id": 123}. The account ID is optional and defaults to the platform’s default connected account. TikTok also accepts caption, privacy_level, allow_comment, allow_duet, allow_stitch, brand_content, brand_organic and consent.
02

Create and queue a video

Use mode: "draft" to create a reviewable draft. Use mode: "queue" only when the payload is final and the connected destinations are ready.

curl -X POST https://vidmfy.com/api/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-842-launch" \
  -d '{
    "title": "Discover our new product",
    "topic": "Explain the key customer benefits",
    "language": "English",
    "video_provider": "auto",
    "video_type": "short",
    "duration_seconds": 60,
    "aspect_ratio": "9:16",
    "destinations": {
      "instagram": {"enabled": true},
      "tiktok": {"enabled": true, "consent": true}
    },
    "scheduled_at": "2026-08-05T10:00:00+02:00",
    "mode": "draft"
  }'
03

Filtering and pagination

List endpoints return data plus a meta object. The maximum page size is 100.

GET /videos?page=1&per_page=25
  &status=published
  &destination=instagram
  &campaign_id=CMP-REFERENCE
  &from=2026-08-01
  &to=2026-08-31
  &search=product
04

Production status lifecycle

Poll the lightweight status route and stop when the video reaches published, failed or cancelled. Store platform publication URLs returned in the destination objects.

draft→queued→generating_script→generating_video→ready_for_validation→ready_to_upload→published

Other actionable states: waiting_video, uploading, budget_paused, failed and cancelled. Use the progress error, event history and retry endpoint to decide the next action.

05

Errors, request IDs and rate limits

Errors always contain a stable machine-readable code. The X-Request-Id response header is also returned in JSON for support and audit purposes.

{
  "ok": false,
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not include the required permission.",
    "details": {"required_scope": "videos:write"}
  },
  "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}
400 Invalid request401 Missing or invalid key403 Scope, IP or account restriction404 Resource not found409 State or idempotency conflict422 Business validation failed429 Rate limit reached500 Internal failure with support code
READY TO CONNECT

Create your first scoped key

Sign in to manage credentials, monitor request history and revoke access instantly.

Create an account →
How it works

A clear workflow from start to finish

01

Create a scoped API key

Sign in, open Developer API and select only the permissions needed by the integration.

02

Authenticate with Bearer

Send the complete key in the Authorization header over HTTPS. Never include it in a URL or client-side application.

03

Send an idempotency key for writes

Give every POST, PATCH and DELETE operation a unique Idempotency-Key value.

04

Store Vidmfy references

Keep the returned VID reference and request ID to follow status, costs, analytics and support investigations.

Designed for real content needs

Ways to use Developer API

Use the feature on its own or connect it to the complete Vidmfy production and publishing workflow.

  • →Create videos from an e-commerce back office
  • →Connect a CRM or customer portal
  • →Queue productions from an internal application
  • →Display production progress in your own interface
  • →Retrieve per-video costs for accounting
  • →Feed a business intelligence dashboard
  • →Validate public source URLs before production
  • →Synchronize published links and analytics
Frequently asked questions

What to know before you start

Where do I create an API key?+

Sign in to Vidmfy and open Developer API in the account menu. The complete secret is displayed only once.

Can an API request create duplicate paid videos?+

Write requests require an Idempotency-Key. Repeating the same request with the same key returns the saved response instead of starting the operation again.

Can I restrict a key?+

Yes. Select exact scopes, a rate limit, an expiration and optionally a list of permitted IPv4 or IPv6 addresses.

Are provider API keys exposed?+

No. Connection summaries report availability and destination identities without returning OAuth tokens or provider secrets.

Does creating a video through the API change pricing?+

No. The API reuses the account plan, trial, wallet and provider billing rules. Costs remain visible through the billing endpoints and the Vidmfy interface.

Explore more

Continue through the Vidmfy workflow

⇄
Flexible API connectionsChoose independently per provider between an easier Vidmfy-managed connection and your own API key with direct provider billing.
Learn more →↻
Production tracking & recoverySee the current production step, completed work and next action, with destination preflight checks and targeted publication retries.
Learn more →$
Costs and walletSee estimated charges before production and review every managed API operation, retry, release and refund under one video reference.
Learn more →
Video production without the repetitive work

Bring your next content idea to life with Vidmfy.

Start with one idea, one photo, one URL or a complete campaign calendar.

Create your Vidmfy account →
3 complete videos free

Create your account and let Vidmfy prepare 3 complete videos for the platforms of your choice — with no commitment and no credit card required.

✓ Scripts and AI generation included✓ No commitment✓ No credit card required
3free videos Create my free account → Up to 60 seconds each · visible VIDMFY.COM watermark