> ## Documentation Index
> Fetch the complete documentation index at: https://docs.submagic.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Export Project

> Trigger the rendering/export process for a completed project to generate the final video

# Export Project

Triggers the rendering/export process for a completed project. This starts the video generation process asynchronously with customizable output parameters.

<Note>
  This endpoint requires authentication and has enhanced rate limits for
  API-generated projects. The export process is asynchronous - use webhooks or
  polling to track completion.
</Note>

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your Submagic API key starting with `sk-`
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier (UUID) of the project to export
</ParamField>

## Request Body (Optional)

All parameters are optional. If not provided, the system uses optimal defaults based on the project's original video metadata.

<ParamField body="fps" type="number" optional>
  Frames per second for the exported video (1-60). Defaults to project's
  original fps or 30.
</ParamField>

<ParamField body="width" type="number" optional>
  Video width in pixels (100-4000). Defaults to project's original width or
  1080\.
</ParamField>

<ParamField body="height" type="number" optional>
  Video height in pixels (100-4000). Defaults to project's original height or
  1920\.
</ParamField>

<ParamField body="webhookUrl" type="string" optional>
  URL to receive notification when export is complete. Must be a valid URL
  format.
</ParamField>

## Prerequisites

Before exporting a project, ensure:

* **Project is transcribed**: Must have words data available
* **Project is not uploading**: Cannot be in "uploading" status
* **Project ownership**: Must belong to the authenticated user
* **API-generated project**: Must be created via API

## Response

<ResponseField name="message" type="string">
  Success message confirming the export has started
</ResponseField>

<ResponseField name="projectId" type="string">
  The unique identifier of the project being exported
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the project after export trigger
</ResponseField>

## Error Responses

<ResponseField name="error" type="string">
  Error code: `NOT_FOUND`, `BAD_REQUEST`, or `INTERNAL_SERVER_ERROR`
</ResponseField>

<ResponseField name="message" type="string">
  Detailed error message explaining the issue
</ResponseField>

## Webhook Notifications

If you provide a `webhookUrl`, the system will send a POST request to your URL when export completes,
including export details and download URL in the notification.

## Export Status Tracking

After triggering an export:

1. **Monitor Progress**: Call `GET /v1/projects/{id}` to check export progress
2. **Check Download URL**: The `downloadUrl` and `directUrl` fields will be populated once rendering is complete

<RequestExample>
  ```bash cURL - Basic Export theme={null}
  curl -X POST "https://api.submagic.co/v1/projects/550e8400-e29b-41d4-a716-446655440000/export" \
    -H "x-api-key: sk-your-api-key-here" \
    -H "Content-Type: application/json"
  ```

  ```bash cURL - Custom Parameters theme={null}
  curl -X POST "https://api.submagic.co/v1/projects/550e8400-e29b-41d4-a716-446655440000/export" \
    -H "x-api-key: sk-your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "fps": 30,
      "width": 1920,
      "height": 1080,
      "webhookUrl": "https://yoursite.com/webhook/export-complete"
    }'
  ```

  ```javascript JavaScript - Basic Export theme={null}
  const exportProject = async (projectId) => {
    const response = await fetch(
      `https://api.submagic.co/v1/projects/${projectId}/export`,
      {
        method: "POST",
        headers: {
          "x-api-key": "sk-your-api-key-here",
          "Content-Type": "application/json",
        },
      }
    );

    const result = await response.json();
    console.log("Export started:", result.message);
    return result;
  };

  // Usage
  const result = await exportProject("550e8400-e29b-41d4-a716-446655440000");
  ```

  ```javascript JavaScript - With Custom Parameters theme={null}
  const exportProjectWithOptions = async (projectId, options = {}) => {
    const response = await fetch(
      `https://api.submagic.co/v1/projects/${projectId}/export`,
      {
        method: "POST",
        headers: {
          "x-api-key": "sk-your-api-key-here",
          "Content-Type": "application/json",
        },
        body: JSON.stringify(options),
      }
    );

    const result = await response.json();
    console.log("Export started:", result.message);
    return result;
  };

  // Usage with options
  const exportOptions = {
    fps: 30,
    width: 1920,
    height: 1080,
    webhookUrl: "https://yoursite.com/webhook/export-complete",
  };

  const result = await exportProjectWithOptions(
    "550e8400-e29b-41d4-a716-446655440000",
    exportOptions
  );
  ```

  ```python Python - Basic Export theme={null}
  import requests

  def export_project(project_id):
      url = f'https://api.submagic.co/v1/projects/{project_id}/export'
      headers = {
          'x-api-key': 'sk-your-api-key-here',
          'Content-Type': 'application/json'
      }

      response = requests.post(url, headers=headers)
      result = response.json()

      print(f"Export started: {result.get('message')}")
      return result

  # Usage
  result = export_project('550e8400-e29b-41d4-a716-446655440000')
  ```

  ```python Python - With Custom Parameters theme={null}
  import requests
  import json

  def export_project_with_options(project_id, options=None):
      url = f'https://api.submagic.co/v1/projects/{project_id}/export'
      headers = {
          'x-api-key': 'sk-your-api-key-here',
          'Content-Type': 'application/json'
      }

      response = requests.post(url, headers=headers, json=options)
      result = response.json()

      print(f"Export started: {result.get('message')}")
      return result

  # Usage with options
  export_options = {
      'fps': 30,
      'width': 1920,
      'height': 1080,
      'webhookUrl': 'https://yoursite.com/webhook/export-complete'
  }

  result = export_project_with_options(
      '550e8400-e29b-41d4-a716-446655440000',
      export_options
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK - Export Started theme={null}
  {
    "message": "Export started successfully",
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "exporting"
  }
  ```

  ```json 404 NOT_FOUND - Project Not Found theme={null}
  {
    "error": "NOT_FOUND",
    "message": "Project doesn't exist or doesn't belong to user"
  }
  ```

  ```json 400 BAD_REQUEST - Project Not Ready theme={null}
  {
    "error": "BAD_REQUEST",
    "message": "Project not ready for export"
  }
  ```

  ```json 400 BAD_REQUEST - Invalid Parameters theme={null}
  {
    "error": "BAD_REQUEST",
    "message": "Invalid fps value. Must be between 1 and 60"
  }
  ```

  ```json 500 INTERNAL_SERVER_ERROR - Export Failed theme={null}
  {
    "error": "INTERNAL_SERVER_ERROR",
    "message": "Export failed to start"
  }
  ```
</ResponseExample>

<Note>
  **Tip**: After triggering an export, use the [Get
  Project](/api-reference/get-project) endpoint to monitor the export progress.
  The `downloadUrl` and `directUrl` fields will be populated once the rendering
  is complete.
</Note>

<Warning>
  **Important**: The export process is asynchronous. The API will return
  immediately after starting the export, but the actual video rendering happens
  in the background. Use webhooks or polling to track completion status.
</Warning>