Developer API

Automate the complete Vidmfy workflow with one professional API

Q: 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.

Connect your website, application, CRM, e-commerce platform or internal workflow to Vidmfy. Manage several publishing accounts, assign their default languages, create optional translations, route every version automatically and follow production without rebuilding the video pipeline yourself.

Start creating →See how it works

✓

Built for multilingual integrations

Manage several destination accounts, language routing and separately traceable translated videos through versioned JSON endpoints.

✓

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 manage several YouTube, Instagram, TikTok or Facebook accounts, label them, assign default languages, create an original plus optional translations, preview automatic routing, follow every 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

JSON

Live contracts and route discovery

These public files are generated from the same canonical catalog as this page. They make it possible to verify every current developer endpoint without relying on an outdated copied list.

REST route catalog · REST OpenAPI 3.1

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.

文

Multiple accounts and automatic language routing

Connect as many destination accounts as your plan allows. Give each connection a private label and a BCP-47 default language, then inspect the routing decision before starting paid production.

GET /connections/routing

PATCH /connections/instagram/12
{
  "connection_label": "French shop",
  "default_language_code": "fr-BE",
  "is_default": true
}

OAuth still requires human consent. Call POST /connections/{platform}/authorization, open the returned URL in a signed-in browser and complete the platform authorization. Tokens and application secrets are never returned by the API.

Existing keys keep their original permissions. Create a new API key containing connections:write before calling connection authorization, update or deletion routes.

Account

Required scope: account:read / connections:read

GET/me

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

GET/capabilities

Supported providers, formats, statuses, languages, localization fields and limits.

GET/connections

Connected publishing accounts and available content/video providers.

Connections

Required scope: connections:read / connections:write

GET/connections/{platform}

List every connected account for one destination platform.

GET/connections/{platform}/{connection_id}

Read one connection without exposing OAuth tokens.

POST/connections/{platform}/authorization

Get the browser authorization URL used to connect another account.

PATCH/connections/{platform}/{connection_id}

Save a label, routing language or platform default.

DELETE/connections/{platform}/{connection_id}

Delete one safe, inactive publishing connection.

GET/connections/routing

Preview automatic account selection for every configured language.

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.

Translations

Required scope: videos:read / videos:write

GET/videos/{VID-reference}/translations

Original video plus every language version and destination status.

POST/videos/{VID-reference}/translations

Replace optional draft translations or queue the complete language group.

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.

Projects

GET/projectsList every publishing project with its editorial context and platform connections.+

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": [
        {
            "id": "PRJ-A1B2C3D4E5",
            "name": "Historical facts",
            "default_language_code": "fr-BE",
            "connection_count": 8,
            "connections": {
                "youtube": [
                    {
                        "id": 4,
                        "connection_label": "History FR",
                        "default_language_code": "fr-BE"
                    }
                ]
            }
        }
    ],
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

POST/projectsCreate a publishing project and enable Project mode. Available during Trial and with active Pro.+

Required scopeconnections: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

nameJSON bodystring, max 120Yes

Project, brand, subject or customer name.

Historical facts

descriptionJSON bodystring, max 4000No

Purpose and general context of the project.

Short educational history videos.

content_themeJSON bodystring, max 4000No

Editorial subjects and boundaries.

Verified historical anecdotes.

target_audienceJSON bodystring, max 3000No

People the project should address.

Curious adults

editorial_toneJSON bodystring, max 190No

Preferred style and tone.

Captivating and factual

default_language_codeJSON bodyBCP-47 code or nullNo

Default editorial language.

fr-BE

colorJSON body#RRGGBBNo

Private organization color.

#596bde

Example response

HTTP 200 OK · application/json

{
    "ok": true,
    "data": {
        "id": "PRJ-A1B2C3D4E5",
        "name": "Historical facts",
        "connection_count": 0
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

GET/projects/{project_id}Return one project and all publishing connections currently linked to it.+

Required scopeconnections:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample

project_idPath or JSON bodyPRJ reference or integerYes in Project mode

Publishing project used to isolate channels, languages and campaigns.

PRJ-A1B2C3D4E5

Example response

HTTP 200 OK · application/json

{
    "ok": true,
    "data": {
        "id": "PRJ-A1B2C3D4E5",
        "name": "Historical facts",
        "default_language_code": "fr-BE",
        "connection_count": 8
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

PATCH/projects/{project_id}Edit the supplied project fields without changing linked connections.+

Required scopeconnections:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample

project_idPath or JSON bodyPRJ reference or integerYes in Project mode

Publishing project used to isolate channels, languages and campaigns.

PRJ-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

nameJSON bodystring, max 120Yes

Project, brand, subject or customer name.

Historical facts

descriptionJSON bodystring, max 4000No

Purpose and general context of the project.

Short educational history videos.

content_themeJSON bodystring, max 4000No

Editorial subjects and boundaries.

Verified historical anecdotes.

target_audienceJSON bodystring, max 3000No

People the project should address.

Curious adults

editorial_toneJSON bodystring, max 190No

Preferred style and tone.

Captivating and factual

default_language_codeJSON bodyBCP-47 code or nullNo

Default editorial language.

fr-BE

colorJSON body#RRGGBBNo

Private organization color.

#596bde

Example response

HTTP 200 OK · application/json

{
    "ok": true,
    "data": {
        "id": "PRJ-A1B2C3D4E5",
        "name": "Historical facts and discoveries",
        "connection_count": 8
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

DELETE/projects/{project_id}Delete an inactive project and its linked destination authorizations while preserving historical videos.+

Required scopeconnections:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample

project_idPath or JSON bodyPRJ reference or integerYes in Project mode

Publishing project used to isolate channels, languages and campaigns.

PRJ-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": {
        "deleted": true,
        "project_id": "PRJ-A1B2C3D4E5",
        "linked_connections_deleted": true,
        "historical_videos_preserved": true
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

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",
            "connection management",
            "language routing",
            "videos",
            "video translations",
            "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"
}

GET/routesReturn the complete machine-readable REST route, scope and parameter catalog used by this documentation.+

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": {
        "base_url": "https://vidmfy.com/api/v1",
        "endpoint_count": 41,
        "generated_at": "2026-08-12T11:00:00+02:00",
        "routes": []
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

GET/openapi.jsonReturn the OpenAPI 3.1 contract generated from the canonical REST endpoint catalog.+

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

{
    "openapi": "3.1.0",
    "info": {
        "title": "Vidmfy REST API",
        "version": "1.0.0"
    },
    "paths": []
}

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, BCP-47 languages and the current account entitlements. Multiple same-platform connections and translations are available during Trial and with active Pro.+

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"
        ],
        "publishing_destinations": [
            "youtube",
            "instagram",
            "tiktok",
            "facebook"
        ],
        "languages": {
            "en": "English",
            "fr-BE": "French (Belgium)",
            "nl-BE": "Dutch (Belgium)"
        },
        "entitlements": {
            "multiple_destination_connections": true,
            "video_translations": true,
            "required_plan": "pro",
            "available_during_trial": true
        },
        "localization": {
            "maximum_target_languages": 20
        },
        "limits": {
            "publishing_connections_per_platform": null,
            "translation_languages_per_request": 20
        }
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

GET/connectionsReturn safe provider availability and connected publishing destinations, including their routing language, 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",
                    "external_id": "UC123",
                    "default_language_code": "en",
                    "language": "English",
                    "is_default": true,
                    "last_verified_at": "2026-08-02 09:00:00"
                }
            ],
            "instagram": [
                {
                    "id": 12,
                    "name": "@examplebrand_fr",
                    "external_id": "17841400000000000",
                    "default_language_code": "fr-BE",
                    "language": "French (Belgium)",
                    "is_default": true,
                    "last_verified_at": "2026-08-02 09:00:00"
                }
            ]
        }
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

Connections

GET/connections/{platform}List every connected account for one destination platform, including custom label, official identity, default language and default flag.+

Required scopeconnections:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample

platformPathyoutube | instagram | tiktok | facebookYes

Publishing platform whose connected accounts are being managed.

instagram

Example response

HTTP 200 OK · application/json

{
    "ok": true,
    "data": [
        {
            "platform": "instagram",
            "id": 12,
            "name": "French shop",
            "platform_name": "examplebrand_fr",
            "connection_label": "French shop",
            "default_language_code": "fr-BE",
            "language": "French (Belgium)",
            "external_id": "17841400000000000",
            "is_default": true,
            "last_verified_at": "2026-08-02 09:00:00"
        }
    ],
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

GET/connections/{platform}/{connection_id}Return one safe publishing connection without exposing OAuth tokens or application secrets.+

Required scopeconnections:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample

platformPathyoutube | instagram | tiktok | facebookYes

Publishing platform whose connected accounts are being managed.

instagram

connection_idPathpositive integerYes

Account ID returned by GET /connections or GET /connections/{platform}.

12

Example response

HTTP 200 OK · application/json

{
    "ok": true,
    "data": {
        "platform": "instagram",
        "id": 12,
        "name": "French shop",
        "platform_name": "examplebrand_fr",
        "connection_label": "French shop",
        "default_language_code": "fr-BE",
        "language": "French (Belgium)",
        "external_id": "17841400000000000",
        "is_default": true,
        "last_verified_at": "2026-08-02 09:00:00"
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

POST/connections/{platform}/authorizationReturn an OAuth URL. The first account is available to every eligible subscription; adding another account on the same platform requires Trial or active Pro. Supply connection_id to reconnect an existing account without adding one.+

Required scopeconnections:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample

platformPathyoutube | instagram | tiktok | facebookYes

Publishing platform whose connected accounts are being managed.

instagram

Idempotency-KeyHeaderstring · 8–120Yes

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

order-1842-video-1

connection_idJSON bodyintegerNo

Existing connection to reauthorize. Omit it only when adding a new account.

12

Example response

HTTP 200 OK · application/json

{
    "ok": true,
    "data": {
        "platform": "instagram",
        "authorization_url": "https://vidmfy.com/instagram-oauth.php?account_id=12",
        "requires_user_consent": true,
        "supports_multiple_accounts": true,
        "multiple_accounts_entitlement": "trial_or_pro",
        "existing_connections": 2
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

PATCH/connections/{platform}/{connection_id}Change a private connection label, its default routing language or the platform default account. Only supplied fields are changed.+

Required scopeconnections:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample

platformPathyoutube | instagram | tiktok | facebookYes

Publishing platform whose connected accounts are being managed.

instagram

connection_idPathpositive integerYes

Account ID returned by GET /connections or GET /connections/{platform}.

12

Idempotency-KeyHeaderstring · 8–120Yes

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

order-1842-video-1

connection_labelJSON bodystring · max 120 | nullNo

Private label used to identify this connection in Vidmfy and API payloads. Empty or null removes the custom label.

French shop

default_language_codeJSON bodyBCP-47 code | nullNo

Default content language used by automatic translation routing. Empty or null disables language routing for this connection.

fr-BE

project_idJSON bodyPRJ reference | nullNo

Assign this publishing account to a project, or null to leave it unassigned.

PRJ-A1B2C3D4E5

is_defaultJSON bodybooleanNo

When true, makes this the platform default and removes the default flag from the other accounts on that platform.

true

Example response

HTTP 200 OK · application/json

{
    "ok": true,
    "data": {
        "platform": "instagram",
        "id": 12,
        "name": "French shop",
        "platform_name": "examplebrand_fr",
        "connection_label": "French shop",
        "default_language_code": "fr-BE",
        "language": "French (Belgium)",
        "external_id": "17841400000000000",
        "is_default": true
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

DELETE/connections/{platform}/{connection_id}Completely remove one platform authorization when it is not used by an active production. Historical videos remain preserved.+

Required scopeconnections:writeBearer or X-API-Key authentication required

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample

platformPathyoutube | instagram | tiktok | facebookYes

Publishing platform whose connected accounts are being managed.

instagram

connection_idPathpositive integerYes

Account ID returned by GET /connections or GET /connections/{platform}.

12

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": {
        "deleted": true,
        "platform": "instagram",
        "account_id": 12,
        "historical_videos_preserved": true,
        "new_default_account_id": 15
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

GET/connections/routingPreview automatic multilingual routing before creating a video. Shows all matching accounts and the account selected on each platform for every language.+

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": {
        "routing_mode": "default_language",
        "languages": [
            {
                "language_code": "fr-BE",
                "language": "French (Belgium)",
                "platforms": {
                    "youtube": [
                        {
                            "platform": "youtube",
                            "account_id": 4,
                            "connection_label": "Belgium channel",
                            "platform_name": "Example Channel",
                            "is_default": true
                        }
                    ],
                    "instagram": [
                        {
                            "platform": "instagram",
                            "account_id": 12,
                            "connection_label": "French shop",
                            "platform_name": "examplebrand_fr",
                            "is_default": true
                        }
                    ]
                },
                "automatic_routes": {
                    "youtube": 4,
                    "instagram": 12
                }
            }
        ],
        "connections_without_language": [],
        "rule": "For each translated language, Vidmfy selects the default matching account on every platform."
    },
    "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

project_idQueryPRJ referenceNo

Return videos linked to one publishing project.

PRJ-A1B2C3D4E5

language_codeQueryBCP-47 codeNo

Return only this original or translated language.

fr-BE

localization_group_idQueryMLG referenceNo

Return all language versions belonging to one localization group.

MLG-K2L3M4N5P6

localization_roleQueryoriginal | translatedNo

Return only originals or translated variants.

translated

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
            },
            "localization": {
                "group_id": "MLG-K2L3M4N5P6",
                "role": "original",
                "language_code": "en",
                "language": "English",
                "source_video_id": null,
                "status": "grouped"
            },
            "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 draft or queue an original plus optional language variants. Each translated version receives its own VID reference and routes to matching destination languages.+

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

project_idJSON bodyPRJ referenceRequired in Project mode

Project returned by GET /projects. Every selected destination must belong to it.

PRJ-A1B2C3D4E5

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"]

product_photo_idJSON body40-character upload id with extensionNo

Protected photo returned by POST /media/photos. Activates the photo-led production workflow.

4f7c1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b.jpg

retouch_photoJSON bodybooleanNo

When product_photo_id is supplied, request the separately billed protected photo-retouch stage.

true

Communication goal used to direct a photo-led production. Default: sell.

sell

duration_secondsJSON bodyintegerNo

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

60

languageJSON bodylanguage nameNo

Original video language. Kept for backward compatibility; prefer localization.source_language_code.

English

language_codeJSON bodyBCP-47 codeNo

Original language code. Kept for backward compatibility; prefer localization.source_language_code.

en

translation_languagesJSON bodyarray of BCP-47 codes · max 20No

Backward-compatible alias of localization.target_languages. An empty array creates no translation.

["fr-BE","nl-BE"]

localizationJSON bodyobjectNo

Controls the source language, optional translations and automatic routing.

{"source_language_code":"en","translate":true,"target_languages":["fr-BE","nl-BE"]}

localization.source_language_codeJSON bodyBCP-47 codeNo

Language of the original title, topic and description.

en

localization.translateJSON bodybooleanNo

Set false to create only the original video, even when target_languages is present. Default: true.

true

localization.target_languagesJSON bodyarray of BCP-47 codes · max 20No

One independently billed and tracked video is created per language and routed by connection default language.

["fr-BE","nl-BE"]

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.*.connection_labelJSON bodystringNo

Alternative to account_id. Must exactly match one custom connection label; ambiguous labels are rejected.

Main French channel

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
        },
        "localization": {
            "group_id": "MLG-K2L3M4N5P6",
            "role": "original",
            "language_code": "en",
            "language": "English",
            "source_video_id": null,
            "status": "grouped"
        },
        "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",
        "language_versions": [
            {
                "id": "VID-A1B2C3D4E5",
                "role": "original",
                "language_code": "en",
                "language": "English",
                "status": "draft",
                "destinations": {
                    "instagram": {
                        "enabled": true,
                        "account_id": 21
                    }
                }
            },
            {
                "id": "VID-F6G7H8J9K0",
                "role": "translated",
                "language_code": "fr-BE",
                "language": "French (Belgium)",
                "status": "draft",
                "destinations": {
                    "instagram": {
                        "enabled": true,
                        "account_id": 12
                    }
                }
            }
        ]
    },
    "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
        },
        "localization": {
            "group_id": "MLG-K2L3M4N5P6",
            "role": "original",
            "language_code": "en",
            "language": "English",
            "source_video_id": null,
            "status": "grouped"
        },
        "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"
}

Translations

GET/videos/{video_id}/translationsReturn the original video and every active translated version with its own VID reference, language, destinations and publication status. A translated VID may also be supplied.+

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": {
        "group_id": "MLG-K2L3M4N5P6",
        "source_video": {
            "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
            },
            "localization": {
                "group_id": "MLG-K2L3M4N5P6",
                "role": "original",
                "language_code": "en",
                "language": "English",
                "source_video_id": null,
                "status": "grouped"
            },
            "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"
        },
        "translations": [
            {
                "id": "VID-F6G7H8J9K0",
                "title": "Découvrez notre nouveau produit",
                "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
                },
                "localization": {
                    "group_id": "MLG-K2L3M4N5P6",
                    "role": "translated",
                    "language_code": "fr-BE",
                    "language": "French (Belgium)",
                    "source_video_id": "VID-A1B2C3D4E5",
                    "status": "pending_translation"
                },
                "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"
            }
        ],
        "translation_count": 1
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

POST/videos/{video_id}/translationsTrial or active Pro only. Replace the optional translation choices of an original draft. Use mode queue to start the original and every selected language after routing 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

translation_languagesJSON bodyarray of BCP-47 codes · max 20Yes*

Required unless localization.target_languages or translate=false is supplied. Empty removes draft translations.

["fr-BE","nl-BE"]

translateJSON bodybooleanNo

Set false to remove every draft translation and keep only the original.

true

localization.target_languagesJSON bodyarray of BCP-47 codes · max 20No

Structured alternative to translation_languages.

["fr-BE","nl-BE"]

localization.translateJSON bodybooleanNo

Structured alternative to translate.

true

modeJSON bodydraft | queueNo

Draft only prepares variants. Queue starts protected production. Default: draft.

draft

Example response

HTTP 200 OK · application/json

{
    "ok": true,
    "data": {
        "group_id": "MLG-K2L3M4N5P6",
        "source_video": {
            "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
            },
            "localization": {
                "group_id": "MLG-K2L3M4N5P6",
                "role": "original",
                "language_code": "en",
                "language": "English",
                "source_video_id": null,
                "status": "grouped"
            },
            "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"
        },
        "translations": [
            {
                "id": "VID-F6G7H8J9K0",
                "status": "draft",
                "localization": {
                    "role": "translated",
                    "language_code": "fr-BE",
                    "source_video_id": "VID-A1B2C3D4E5"
                },
                "destinations": {
                    "instagram": {
                        "enabled": true,
                        "account_id": 12
                    }
                }
            }
        ],
        "translation_count": 1,
        "requested_languages": [
            "fr-BE"
        ],
        "mode": "draft"
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

Videos

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

project_idJSON bodyPRJ referenceNo

Project returned by GET /projects. Every selected destination must belong to it.

PRJ-A1B2C3D4E5

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"]

product_photo_idJSON body40-character upload id with extensionNo

Protected photo returned by POST /media/photos. Activates the photo-led production workflow.

4f7c1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b.jpg

retouch_photoJSON bodybooleanNo

When product_photo_id is supplied, request the separately billed protected photo-retouch stage.

true

Communication goal used to direct a photo-led production. Default: sell.

sell

duration_secondsJSON bodyintegerNo

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

60

languageJSON bodylanguage nameNo

Original video language. Kept for backward compatibility; prefer localization.source_language_code.

English

language_codeJSON bodyBCP-47 codeNo

Original language code. Kept for backward compatibility; prefer localization.source_language_code.

en

translation_languagesJSON bodyarray of BCP-47 codes · max 20No

Backward-compatible alias of localization.target_languages. An empty array creates no translation.

["fr-BE","nl-BE"]

localizationJSON bodyobjectNo

Controls the source language, optional translations and automatic routing.

{"source_language_code":"en","translate":true,"target_languages":["fr-BE","nl-BE"]}

localization.source_language_codeJSON bodyBCP-47 codeNo

Language of the original title, topic and description.

en

localization.translateJSON bodybooleanNo

Set false to create only the original video, even when target_languages is present. Default: true.

true

localization.target_languagesJSON bodyarray of BCP-47 codes · max 20No

One independently billed and tracked video is created per language and routed by connection default language.

["fr-BE","nl-BE"]

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

destinations.*.connection_labelJSON bodystringNo

Alternative to account_id. Must exactly match one custom connection label; ambiguous labels are rejected.

Main French channel

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
        },
        "localization": {
            "group_id": "MLG-K2L3M4N5P6",
            "role": "original",
            "language_code": "en",
            "language": "English",
            "source_video_id": null,
            "status": "grouped"
        },
        "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
        },
        "localization": {
            "group_id": "MLG-K2L3M4N5P6",
            "role": "original",
            "language_code": "en",
            "language": "English",
            "source_video_id": null,
            "status": "grouped"
        },
        "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
        },
        "localization": {
            "group_id": "MLG-K2L3M4N5P6",
            "role": "original",
            "language_code": "en",
            "language": "English",
            "source_video_id": null,
            "status": "grouped"
        },
        "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
        },
        "localization": {
            "group_id": "MLG-K2L3M4N5P6",
            "role": "original",
            "language_code": "en",
            "language": "English",
            "source_video_id": null,
            "status": "grouped"
        },
        "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, production counts and multilingual configuration.+

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",
            "translation_languages": [
                "fr-BE",
                "nl-BE"
            ],
            "localization": {
                "source_language_code": "en",
                "translation_languages": [
                    "fr-BE",
                    "nl-BE"
                ],
                "language_versions_per_publication": 3
            },
            "destinations": "instagram,tiktok",
            "planned_videos": 36,
            "video_count": 36
        }
    ],
    "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, languages 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",
        "translation_languages": [
            "fr-BE",
            "nl-BE"
        ],
        "localization": {
            "source_language_code": "en",
            "translation_languages": [
                "fr-BE",
                "nl-BE"
            ],
            "language_versions_per_publication": 3
        },
        "destinations": "instagram,tiktok",
        "planned_videos": 36,
        "video_count": 36
    },
    "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

project_idQueryPRJ referenceNo

Return videos linked to one publishing project.

PRJ-A1B2C3D4E5

language_codeQueryBCP-47 codeNo

Return only this original or translated language.

fr-BE

localization_group_idQueryMLG referenceNo

Return all language versions belonging to one localization group.

MLG-K2L3M4N5P6

localization_roleQueryoriginal | translatedNo

Return only originals or translated variants.

translated

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
            },
            "localization": {
                "group_id": "MLG-K2L3M4N5P6",
                "role": "original",
                "language_code": "en",
                "language": "English",
                "source_video_id": null,
                "status": "grouped"
            },
            "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"
}

Media

POST/media/photosUpload and validate a protected product photo before creating a photo-led video.+

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

photoMultipart bodyJPEG, PNG or WebP fileYes

Product image within the configured upload size and dimension limits.

product.jpg

Example response

HTTP 200 OK · application/json

{
    "ok": true,
    "data": {
        "photo_id": "4f7c1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b.jpg",
        "name": "product.jpg",
        "size": 57988,
        "mime": "image/jpeg",
        "width": 1080,
        "height": 1350,
        "content_url": "https://vidmfy.com/api/v1/media/photos/4f7c1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b.jpg"
    },
    "request_id": "2f19a913-8f91-4d9b-9f95-62d43af81362"
}

GET/media/photos/{photo_id}Stream an owned protected product photo.+

Required scopevideos:readBearer, X-API-Key or ?api_key= for direct browser testing

Accepted parameters

ParameterLocationTypeRequired?DescriptionExample

photo_idPath40 hexadecimal characters plus jpg, png or webpYes

Photo identifier returned by POST /media/photos.

4f7c1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b.jpg

Example response

HTTP 200 OK · application/json

{
    "binary": "Image bytes",
    "content_type": "image/jpeg | image/png | image/webp"
}

DELETE/media/photos/{photo_id}Delete an owned protected photo that is no longer needed.+

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

photo_idPath40 hexadecimal characters plus jpg, png or webpYes

Photo identifier returned by POST /media/photos.

4f7c1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b.jpg

Example response

HTTP 200 OK · application/json

{
    "ok": true,
    "data": {
        "deleted": true,
        "photo_id": "4f7c1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b.jpg"
    },
    "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"
}

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.

localization.source_language_codeBCP-47 codeNoOriginal language. Defaults to the account language.

localization.translatebooleanNoTranslation remains optional. False creates only the original.

localization.target_languagesarray · max 20NoCreates one separately tracked and billed version per selected 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}, or use an exact private connection_label. If neither is supplied, the platform default is used. Translated variants are routed separately through default_language_code. TikTok also accepts caption, privacy_level, allow_comment, allow_duet, allow_stitch, brand_content, brand_organic and consent.

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",
    "localization": {
      "source_language_code": "en",
      "translate": true,
      "target_languages": ["fr-BE", "nl-BE"]
    },
    "video_provider": "auto",
    "video_type": "short",
    "duration_seconds": 60,
    "aspect_ratio": "9:16",
    "destinations": {
      "instagram": {"enabled": true, "connection_label": "English main account"},
      "tiktok": {"enabled": true, "consent": true}
    },
    "scheduled_at": "2026-08-05T10:00:00+02:00",
    "mode": "draft"
  }'

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

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.

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

Create an account →

How it works

A clear workflow from start to finish

Create a scoped API key

Authenticate with Bearer

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

Send an idempotency key for writes

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

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.

→Manage several publishing accounts per platform
→Assign a default language and private label to each destination
→Create multilingual videos from an e-commerce back office
→Route translations to matching accounts automatically
→Connect a CRM or customer portal
→Display production progress in your own interface
→Retrieve per-video costs for accounting
→Synchronize published links and analytics

Frequently asked questions

What to know before you start

Where do I create an API key?+

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.

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 →