API v1

VidAI API Reference

Create Faceless Videos and create, edit, generate, and render Faceless Shorts programmatically. This reference documents every bearer-authenticated v1 endpoint, exact request contracts, asynchronous states, and recoverable failures.

Base URL

https://vid.ai/api/v1

Getting started

Authentication

Bearer authentication is required for every endpoint documented below. Create a token from the Developer settings. Tokens begin with vidai_v1_, are shown only when created, and should be stored as secrets.

Shell setup

export VIDAI_BASE_URL="https://vid.ai"
export VIDAI_API_TOKEN="vidai_v1_your_token"
export PROJECT_ID="your_project_id"

Authorization header

Authorization: Bearer $VIDAI_API_TOKEN

Token security

Never expose a token in browser code, URLs, public repositories, screenshots, or logs. Revoke exposed tokens immediately. Each account can have up to 10 active tokens, and tokens may have an expiration date.

Verify your token

cURL

curl "$VIDAI_BASE_URL/api/v1/me"   -H "Authorization: Bearer $VIDAI_API_TOKEN"

Authentication failure

401 response

{
  "error": {
    "code": "invalid_api_token",
    "message": "A valid bearer API token is required."
  }
}

Getting started

Request and response conventions

JSON: POST bodies use Content-Type: application/json.
Strict validation: Unknown body or query fields are rejected with HTTP 422.
Request IDs: Workflow responses include requestId and expose the same value in X-Request-Id.
Caching: API responses use Cache-Control: no-store.
Dates: Timestamps are ISO 8601 UTC strings.
Asynchronous work: HTTP 202 means work started or remains in progress. Poll the corresponding status endpoint every 5 seconds.
Idempotent state handling: Repeating generate or render while active does not enqueue duplicate work. Calling after completion returns the completed state.

Standard envelope

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6"
  }
}

Getting started

Faceless Shorts workflow

Create

Generate scripts and section images.

Edit

Optionally replace scripts or images.

Generate

Queue narration and captions.

Poll media

Wait for MEDIA_GENERATED.

Render

Queue the final Lambda render.

Poll render

Wait for GENERATED and videoLink.

Polling interval

Poll status endpoints every 5 seconds. Stop polling on generated or failed. Status endpoints are read-only and never start work.

GET/api/v1/me

Get authenticated account

Verify a bearer token and return the account identity associated with it.

cURL

curl "$VIDAI_BASE_URL/api/v1/me"   -H "Authorization: Bearer $VIDAI_API_TOKEN"

200 response

{
  "data": {
    "user": {
      "id": "clx_user_id",
      "email": "[email protected]",
      "name": "Creator"
    }
  }
}

GET/api/v1/projects

List projects

Return visible projects owned by the authenticated account with pagination and optional filters.

Name	Type	Required	Description
page	integer	No	Page number. Defaults to 1.
limit	integer	No	Items per page. Defaults to 20; maximum 100.
status	enum	No	One of: DRAFT, ONGOING, MEDIA_GENERATING, MEDIA_GENERATED, RENDERING, GENERATED.
tool	string	No	Exact tool identifier, such as faceless-shorts.
search	string	No	Project-name search, up to 100 characters.

cURL

curl "$VIDAI_BASE_URL/api/v1/projects?page=1&limit=20&tool=faceless-shorts&status=MEDIA_GENERATED"   -H "Authorization: Bearer $VIDAI_API_TOKEN"

200 response

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projects": [
      {
        "id": "cmu2cthbl0001ijs3yk8nkgb6",
        "name": "History in 60 seconds",
        "tool": "faceless-shorts",
        "status": "MEDIA_GENERATED",
        "inputType": "PROMPT",
        "thumbnail": "https://storage.example/image.webp",
        "latestVersion": 2,
        "createdAt": "2026-09-15T08:10:00.000Z",
        "updatedAt": "2026-09-15T08:14:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalItems": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}

POST/api/v1/faceless-shorts/create

Create a Faceless Shorts project

Create a project, generate its scripts and section images, and return editable sections. Exactly one of prompt or script must be supplied. This endpoint performs content generation before responding.

Name	Type	Required	Description
name	string	Yes	Project name, 1-100 characters.
prompt	string	Conditional	Generation prompt. Required when script is omitted.
script	string	Conditional	Complete source script. Required when prompt is omitted.
duration	60 \| 90	Yes	Requested duration in seconds.
narrator	enum	Yes	Narrator key from the allowed-values section.
imageTheme	enum	Yes	Image theme from the allowed-values section.

Credits and subscription

An active paid subscription and at least 5 credits are required. Successful content generation consumes 5 credits.

cURL - prompt

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-shorts/create"   -H "Authorization: Bearer $VIDAI_API_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "The lost city of Atlantis",
    "prompt": "Explain the most compelling theories about Atlantis",
    "duration": 60,
    "narrator": "matt",
    "imageTheme": "cinematic"
  }'

cURL - script

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-shorts/create"   -H "Authorization: Bearer $VIDAI_API_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "A short history of flight",
    "script": "For centuries, humans looked at birds and imagined flight...",
    "duration": 60,
    "narrator": "rachel",
    "imageTheme": "natural"
  }'

201 response

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "project": {
      "id": "cmu2cthbl0001ijs3yk8nkgb6",
      "name": "The lost city of Atlantis",
      "tool": "faceless-shorts",
      "status": "DRAFT",
      "inputType": "PROMPT",
      "latestVersion": 0,
      "createdAt": "2026-09-15T08:10:00.000Z",
      "updatedAt": "2026-09-15T08:10:00.000Z"
    },
    "version": {
      "id": "cmu_version_id",
      "number": 0,
      "status": "DRAFT",
      "createdAt": "2026-09-15T08:10:00.000Z"
    },
    "sections": [
      {
        "index": 0,
        "script": "For centuries, sailors told stories of a lost city...",
        "image": "https://storage.example/image_0.webp"
      }
    ]
  }
}

POST/api/v1/faceless-shorts/edit-sections

Edit generated sections

Replace the script, image, or both for one or more generated sections before media generation.

Name	Type	Required	Description
projectId	string	Yes	Faceless Shorts project ID.
sections	array	Yes	Between 1 and 50 unique section updates.
sections[].index	integer	Yes	Zero-based existing section index.
sections[].script	string	Conditional	Replacement narration, up to 10,000 characters.
sections[].image	HTTP URL	Conditional	Replacement image URL. Provide script, image, or both.

cURL

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-shorts/edit-sections"   -H "Authorization: Bearer $VIDAI_API_TOKEN"   -H "Content-Type: application/json"   -d '{
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
    "sections": [
      {
        "index": 0,
        "script": "A revised opening hook for the video.",
        "image": "https://example.com/replacement.webp"
      },
      {
        "index": 2,
        "script": "A revised closing section."
      }
    ]
  }'

200 response

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
    "version": {
      "id": "cmu_version_id",
      "number": 2,
      "status": "DRAFT",
      "createdAt": "2026-09-15T08:12:00.000Z"
    },
    "sections": [
      {
        "index": 0,
        "script": "A revised opening hook for the video.",
        "image": "https://storage.example/replacement.webp"
      },
      {
        "index": 2,
        "script": "A revised closing section.",
        "image": "https://storage.example/image_2.webp"
      }
    ]
  }
}

POST/api/v1/faceless-shorts/generate

Start media generation

Queue narration audio, merged speech, timestamped captions, and section timing. The request returns after the durable job is queued; it does not wait for generation to finish.

Name	Type	Required	Description
projectId	string	Yes	Project containing generated scripts and valid storage data.
retry	boolean	No	Defaults to false. Set true only after a failed generation.

cURL

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-shorts/generate"   -H "Authorization: Bearer $VIDAI_API_TOKEN"   -H "Content-Type: application/json"   -d '{"projectId":"cmu2cthbl0001ijs3yk8nkgb6"}'

HTTP	State	Project status	Meaning
202	generation_started	MEDIA_GENERATING	A background job was queued.
202	generation_in_progress	MEDIA_GENERATING	Generation was already active; no duplicate job was created.
200	generated	MEDIA_GENERATED or GENERATED	Media already exists; no regeneration occurred.

202 - started

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
    "state": "generation_started",
    "status": "MEDIA_GENERATING",
    "message": "Media generation started. Check again later."
  }
}

202 - already running

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
    "state": "generation_in_progress",
    "status": "MEDIA_GENERATING",
    "message": "Media generation is already in progress. Check again later."
  }
}

200 - generated

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
    "state": "generated",
    "status": "MEDIA_GENERATED",
    "message": "Media generated successfully.",
    "version": {
      "id": "cmu_media_version_id",
      "number": 3,
      "status": "MEDIA_GENERATED",
      "createdAt": "2026-09-15T08:14:00.000Z"
    }
  }
}

cURL - retry failed generation

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-shorts/generate"   -H "Authorization: Bearer $VIDAI_API_TOKEN"   -H "Content-Type: application/json"   -d '{"projectId":"cmu2cthbl0001ijs3yk8nkgb6","retry":true}'

GET/api/v1/faceless-shorts/generation-status

Get media generation status

Read the persisted generation state. This endpoint never starts, retries, or mutates generation.

Name	Type	Required	Description
projectId	string	Yes	Passed as a query parameter.

cURL

curl "$VIDAI_BASE_URL/api/v1/faceless-shorts/generation-status?projectId=cmu2cthbl0001ijs3yk8nkgb6"   -H "Authorization: Bearer $VIDAI_API_TOKEN"

HTTP	State	Project status	Meaning
200	not_started	DRAFT or ONGOING	Media generation has not started.
200	generation_in_progress	MEDIA_GENERATING	The background worker is generating media.
200	generated	MEDIA_GENERATED or GENERATED	Media generation completed.
200	failed	Previous status	All worker attempts failed; an explicit retry is available.

200 - failed state

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
    "state": "failed",
    "status": "DRAFT",
    "message": "Media generation failed.",
    "error": {
      "code": "media_generation_failed",
      "message": "Retry generation with retry set to true.",
      "retryable": true
    }
  }
}

POST/api/v1/faceless-shorts/render

Start video rendering

Queue a Remotion Lambda render for a MEDIA_GENERATED project. The request returns after queueing and does not wait for the video render.

Name	Type	Required	Description
projectId	string	Yes	Project whose status is MEDIA_GENERATED.
retry	boolean	No	Defaults to false. Set true only after a failed render.

cURL

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-shorts/render"   -H "Authorization: Bearer $VIDAI_API_TOKEN"   -H "Content-Type: application/json"   -d '{"projectId":"cmu2cthbl0001ijs3yk8nkgb6"}'

HTTP	State	Project status	Meaning
202	render_started	RENDERING	A background render job was queued.
202	rendering_in_progress	RENDERING	Rendering was already active; no duplicate Lambda render was started.
200	generated	GENERATED	A rendered video already exists; it was not rendered again.

202 - started

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
    "state": "render_started",
    "status": "RENDERING",
    "message": "Rendering started. Check again later."
  }
}

200 - generated

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
    "state": "generated",
    "status": "GENERATED",
    "message": "Rendering completed successfully.",
    "version": {
      "id": "cmu_render_version_id",
      "number": 4,
      "status": "GENERATED",
      "createdAt": "2026-09-15T08:18:00.000Z"
    },
    "videoLink": "https://render.example/video.mp4"
  }
}

cURL - retry failed render

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-shorts/render"   -H "Authorization: Bearer $VIDAI_API_TOKEN"   -H "Content-Type: application/json"   -d '{"projectId":"cmu2cthbl0001ijs3yk8nkgb6","retry":true}'

GET/api/v1/faceless-shorts/rendering-status

Get rendering status

Read the persisted rendering state without starting work. Progress percentages are intentionally not returned.

Name	Type	Required	Description
projectId	string	Yes	Passed as a query parameter.

cURL

curl "$VIDAI_BASE_URL/api/v1/faceless-shorts/rendering-status?projectId=cmu2cthbl0001ijs3yk8nkgb6"   -H "Authorization: Bearer $VIDAI_API_TOKEN"

HTTP	State	Project status	Meaning
200	not_ready	DRAFT, ONGOING, or MEDIA_GENERATING	Media must finish before rendering.
200	not_started	MEDIA_GENERATED	The project is ready, but rendering has not started.
200	rendering_in_progress	RENDERING	The render worker is active. No percentage is returned.
200	generated	GENERATED	Rendering completed and videoLink is available.
200	failed	MEDIA_GENERATED	All render attempts failed; an explicit retry is available.

200 - rendering

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
    "state": "rendering_in_progress",
    "status": "RENDERING",
    "message": "Rendering is already in progress. Check again later."
  }
}

200 - failed state

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "data": {
    "projectId": "cmu2cthbl0001ijs3yk8nkgb6",
    "state": "failed",
    "status": "MEDIA_GENERATED",
    "message": "Rendering failed.",
    "error": {
      "code": "render_failed",
      "message": "Retry rendering with retry set to true.",
      "retryable": true
    }
  }
}

POST/api/v1/faceless-videos/create

Create a Faceless Video project

Create a long-form Faceless Video project and generate its editable script sections. Duration is supplied in minutes, while voice ID and speaking speed are resolved from the narrator key.

Name	Type	Required	Description
name	string	Yes	Project name, 1-100 characters. The API preserves this name.
prompt	string	Conditional	Generation prompt. Required when script is omitted.
script	string	Conditional	Complete source script. Required when prompt is omitted.
duration	integer	Yes	Requested duration in minutes, from 1 through 20. Your plan may enforce a lower maximum.
narrator	enum	Yes	Narrator key from the Faceless Video allowed-values section.

PRO plan and credits

A PRO subscription is required. The account must have 5 credits per requested minute available. Project creation deducts the first 5 credits; later media generation handles any remaining duration credits.

cURL - prompt

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-videos/create"     -H "Authorization: Bearer $VIDAI_API_TOKEN"     -H "Content-Type: application/json"     -d '{
        "name": "The future of robotics",
        "prompt": "Explain how humanoid robots may change daily life",
        "duration": 5,
        "narrator": "matt"
    }'

cURL - script

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-videos/create"     -H "Authorization: Bearer $VIDAI_API_TOKEN"     -H "Content-Type: application/json"     -d '{
        "name": "A history of robotics",
        "script": "The history of robotics begins with ancient mechanical inventions...",
        "duration": 5,
        "narrator": "rachel"
    }'

201 response

{
    "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
    "data": {
        "project": {
            "id": "cmu_video_project_id",
            "name": "The future of robotics",
            "tool": "faceless-video",
            "status": "DRAFT",
            "inputType": "PROMPT",
            "latestVersion": 0,
            "createdAt": "2026-09-15T09:10:00.000Z",
            "updatedAt": "2026-09-15T09:10:00.000Z"
        },
        "version": {
            "id": "cmu_video_version_id",
            "number": 0,
            "status": "DRAFT",
            "createdAt": "2026-09-15T09:10:00.000Z"
        },
        "sections": [
            {
                "index": 0,
                "title": "Machines enter daily life",
                "content": "Humanoid robots are moving from research labs into homes and workplaces..."
            }
        ]
    }
}

POST/api/v1/faceless-videos/edit-sections

Edit Faceless Video sections

Update the title, content, or both for one or more existing sections. Updates are partial and identified by the zero-based indexes returned from project creation.

Name	Type	Required	Description
projectId	string	Yes	Faceless Video project ID.
sections	array	Yes	Between 1 and 100 unique indexed section updates.
sections[].index	integer	Yes	Zero-based existing section index.
sections[].title	string	Conditional	Replacement title, up to 500 characters.
sections[].content	string	Conditional	Replacement section content, up to 100,000 characters. Provide title, content, or both.

Project access

A PRO subscription is required. Only sections from a Faceless Video project owned by the authenticated account can be edited.

cURL

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-videos/edit-sections"     -H "Authorization: Bearer $VIDAI_API_TOKEN"     -H "Content-Type: application/json"     -d '{
        "projectId": "cmu_video_project_id",
        "sections": [
            {
                "index": 0,
                "title": "Robots enter daily life",
                "content": "Humanoid robots are moving from research labs into homes and workplaces."
            },
            {
                "index": 2,
                "content": "This revised section explains the practical challenges ahead."
            }
        ]
    }'

200 response

{
    "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
    "data": {
        "projectId": "cmu_video_project_id",
        "version": {
            "id": "cmu_video_version_id",
            "number": 1,
            "status": "DRAFT",
            "createdAt": "2026-09-15T09:15:00.000Z"
        },
        "sections": [
            {
                "index": 0,
                "title": "Robots enter daily life",
                "content": "Humanoid robots are moving from research labs into homes and workplaces."
            },
            {
                "index": 2,
                "title": "Challenges ahead",
                "content": "This revised section explains the practical challenges ahead."
            }
        ]
    }
}

POST/api/v1/faceless-videos/generate

Start Faceless Video media generation

Queue narration, captions, stock footage, scenes, and optional AI images or chapter titles. The endpoint returns immediately after durable queueing and never waits for media generation to complete.

Name	Type	Required	Description
projectId	string	Yes	Faceless Video project containing editable sections.
imageTheme	enum \| null	No	AI image theme. Omit or set null to disable AI images and use stock footage only.
addChapterTitles	boolean	No	Generate chapter-title scenes. Defaults to false.
retry	boolean	No	Defaults to false. Set true only after a failed generation.

Asynchronous generation

A PRO subscription is required. Only one media job can run per project. Poll the generation-status endpoint every 5 seconds until it returns generated or failed.

cURL - stock footage only

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-videos/generate"     -H "Authorization: Bearer $VIDAI_API_TOKEN"     -H "Content-Type: application/json"     -d '{
        "projectId": "cmu_video_project_id",
        "addChapterTitles": false
    }'

cURL - AI images and chapter titles

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-videos/generate"     -H "Authorization: Bearer $VIDAI_API_TOKEN"     -H "Content-Type: application/json"     -d '{
        "projectId": "cmu_video_project_id",
        "imageTheme": "cinematic",
        "addChapterTitles": true
    }'

HTTP	State	Project status	Meaning
202	generation_started	MEDIA_GENERATING	A background media job was queued.
202	generation_in_progress	MEDIA_GENERATING	Generation is already active; no duplicate job was created.
200	generated	MEDIA_GENERATED or GENERATED	Media already exists; no regeneration occurred.

202 - started

{
    "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
    "data": {
        "projectId": "cmu_video_project_id",
        "state": "generation_started",
        "status": "MEDIA_GENERATING",
        "message": "Media generation started. Check again later."
    }
}

200 - generated

{
    "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
    "data": {
        "projectId": "cmu_video_project_id",
        "state": "generated",
        "status": "MEDIA_GENERATED",
        "message": "Media generated successfully.",
        "version": {
            "id": "cmu_media_version_id",
            "number": 2,
            "status": "MEDIA_GENERATED",
            "createdAt": "2026-09-15T09:25:00.000Z"
        }
    }
}

cURL - retry failed generation

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-videos/generate"     -H "Authorization: Bearer $VIDAI_API_TOKEN"     -H "Content-Type: application/json"     -d '{
        "projectId": "cmu_video_project_id",
        "imageTheme": "cinematic",
        "addChapterTitles": true,
        "retry": true
    }'

GET/api/v1/faceless-videos/generation-status

Get Faceless Video generation status

Read the persisted media-generation state. This endpoint never starts, retries, or mutates generation and does not return generated media.

Name	Type	Required	Description
projectId	string	Yes	Passed as a query parameter.

cURL

curl "$VIDAI_BASE_URL/api/v1/faceless-videos/generation-status?projectId=cmu_video_project_id"     -H "Authorization: Bearer $VIDAI_API_TOKEN"

HTTP	State	Project status	Meaning
200	not_started	DRAFT or ONGOING	Media generation has not started.
200	generation_in_progress	MEDIA_GENERATING	The background worker is generating media.
200	generated	MEDIA_GENERATED or GENERATED	Media generation completed.
200	failed	Previous status	All worker attempts failed; retry explicitly through the generate endpoint.

200 - in progress

{
    "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
    "data": {
        "projectId": "cmu_video_project_id",
        "state": "generation_in_progress",
        "status": "MEDIA_GENERATING",
        "message": "Media generation is already in progress. Check again later."
    }
}

POST/api/v1/faceless-videos/render

Start Faceless Video rendering

Queue a Remotion Lambda render for a MEDIA_GENERATED Faceless Video. The endpoint returns after durable queueing and does not wait for rendering to complete.

Name	Type	Required	Description
projectId	string	Yes	Faceless Video project whose status is MEDIA_GENERATED.
retry	boolean	No	Defaults to false. Set true only after a failed render.

Asynchronous rendering

A PRO subscription is required. Only one render can run per project. Poll rendering-status every 5 seconds; no percentage progress is returned.

cURL

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-videos/render"     -H "Authorization: Bearer $VIDAI_API_TOKEN"     -H "Content-Type: application/json"     -d '{"projectId":"cmu_video_project_id"}'

HTTP	State	Project status	Meaning
202	render_started	RENDERING	A background Lambda render job was queued.
202	rendering_in_progress	RENDERING	Rendering is already active; no duplicate render was started.
200	generated	GENERATED	A rendered video already exists and videoLink is returned.

202 - started

{
    "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
    "data": {
        "projectId": "cmu_video_project_id",
        "state": "render_started",
        "status": "RENDERING",
        "message": "Rendering started. Check again later."
    }
}

200 - generated

{
    "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
    "data": {
        "projectId": "cmu_video_project_id",
        "state": "generated",
        "status": "GENERATED",
        "message": "Rendering completed successfully.",
        "version": {
            "id": "cmu_render_version_id",
            "number": 3,
            "status": "GENERATED",
            "createdAt": "2026-09-15T09:35:00.000Z"
        },
        "videoLink": "https://render.example/faceless-video.mp4"
    }
}

cURL - retry failed render

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-videos/render"     -H "Authorization: Bearer $VIDAI_API_TOKEN"     -H "Content-Type: application/json"     -d '{"projectId":"cmu_video_project_id","retry":true}'

GET/api/v1/faceless-videos/rendering-status

Get Faceless Video rendering status

Read the persisted render state without starting or retrying work. The response is state-only while rendering and includes the latest video link after completion.

Name	Type	Required	Description
projectId	string	Yes	Passed as a query parameter.

cURL

curl "$VIDAI_BASE_URL/api/v1/faceless-videos/rendering-status?projectId=cmu_video_project_id"     -H "Authorization: Bearer $VIDAI_API_TOKEN"

HTTP	State	Project status	Meaning
200	not_ready	DRAFT, ONGOING, or MEDIA_GENERATING	Media must finish before rendering.
200	not_started	MEDIA_GENERATED	Media is ready, but rendering has not started.
200	rendering_in_progress	RENDERING	The render worker is active. No percentage is returned.
200	generated	GENERATED	Rendering completed and videoLink is available.
200	failed	MEDIA_GENERATED	All render attempts failed; retry explicitly through the render endpoint.

200 - rendering

{
    "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
    "data": {
        "projectId": "cmu_video_project_id",
        "state": "rendering_in_progress",
        "status": "RENDERING",
        "message": "Rendering is already in progress. Check again later."
    }
}

200 - failed

{
    "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
    "data": {
        "projectId": "cmu_video_project_id",
        "state": "failed",
        "status": "MEDIA_GENERATED",
        "message": "Rendering failed.",
        "error": {
            "code": "render_failed",
            "message": "Retry rendering with retry set to true.",
            "retryable": true
        }
    }
}

Reference

Allowed values

Durations

60, 90 seconds

Narrators

mattadamstonerachelmatildapriyam-v2adamkaylatimmyandyivanthemightymichaelmouserudraallisonrusselljessicalilyWolffsantaClausbillrichardYuryanfredericksurreydariansawyereddiealiciajadelawrencecalebtaliawarrenkaelenflorencewyatt

Image themes

naturalanimecinematiccomic-artisometricwater-colorline-drawinggraffiti-artpixel-artoil-paintingneon-artcubism

Faceless Video durations

1-20 minutes. The account plan may set a lower maximum.

Faceless Video narrators

Faceless Video image themes

Omit imageTheme to generate with stock footage only.

naturalanimecinematiccomic-artisometricwater-colorline-drawinggraffiti-artpixel-artoil-paintingneon-artcubism

Project statuses

DRAFTONGOINGMEDIA_GENERATINGMEDIA_GENERATEDRENDERINGGENERATED

Reference

Errors

Errors use a stable machine-readable code. Validation failures may include field-level details. Store the request ID when contacting support.

HTTP	Common codes	Meaning
400	invalid_token_id	A required identifier is missing or malformed.
401	invalid_api_token	Token is missing, invalid, expired, revoked, or belongs to a disabled account.
402	insufficient_credits	The account does not have enough credits.
403	account_email_required, subscription_required	The account is not eligible for the operation.
404	project_not_found, api_token_not_found	The owned resource was not found.
405	method_not_allowed	Use the documented HTTP method.
409	invalid_project_state, project_state_changed, render_state_changed	The project is not ready or changed during an atomic start.
413	image_too_large	A replacement image exceeds the accepted limit.
422	validation_error, duration_limit_exceeded, script_duration_exceeded, invalid_narrator, section_not_found, invalid_image_url, invalid_image	Request fields, duration, narrator, or section data are invalid.
500	internal_error, media_generation_failed, render_failed	Processing failed. Poll status and retry only when marked retryable.
503	media_generation_unavailable, render_unavailable	The background queue could not accept the job.

{
  "requestId": "98c52d66-19de-4c63-b204-25f6f5125f52",
  "error": {
    "code": "validation_error",
    "message": "The request body is invalid.",
    "details": [
      {
        "path": "projectId",
        "message": "Too small: expected string to have >=1 characters"
      }
    ]
  }
}

Reference

Complete cURL workflow

This condensed sequence assumes project creation has returned a project ID. Replace the sample value or export PROJECT_ID before running it.

1. Create

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-shorts/create"   -H "Authorization: Bearer $VIDAI_API_TOKEN"   -H "Content-Type: application/json"   -d '{"name":"Atlantis","prompt":"Explain Atlantis theories","duration":60,"narrator":"matt","imageTheme":"cinematic"}'

2. Generate media

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-shorts/generate"   -H "Authorization: Bearer $VIDAI_API_TOKEN"   -H "Content-Type: application/json"   -d "{"projectId":"$PROJECT_ID"}"

3. Poll media

curl "$VIDAI_BASE_URL/api/v1/faceless-shorts/generation-status?projectId=$PROJECT_ID"   -H "Authorization: Bearer $VIDAI_API_TOKEN"

4. Start render

curl -X POST "$VIDAI_BASE_URL/api/v1/faceless-shorts/render"   -H "Authorization: Bearer $VIDAI_API_TOKEN"   -H "Content-Type: application/json"   -d "{"projectId":"$PROJECT_ID"}"

5. Poll render

curl "$VIDAI_BASE_URL/api/v1/faceless-shorts/rendering-status?projectId=$PROJECT_ID"   -H "Authorization: Bearer $VIDAI_API_TOKEN"

Polling behavior

Poll every 5 seconds. Stop media polling when state is generated, then start rendering. Stop render polling when state is generated and read videoLink.

Ready to make a request?

Create a scoped token from your VidAI account.

Manage API tokens