Waymark Plugin — Background Actions

The Waymark Plugin provides APIs for starting long-running actions that run in the background. These actions allow you to begin processes such as searching for video topics or generating videos—before the user interacts with the Waymark UI, minimizing wait times and improving the user experience.

Concepts

Topics

A topic is an entity (such as a business) that can be used as the subject of a video generated through Waymark. Topics are created by providing a source URL for the website which contains the most relevant information about the topic (for a business, this could be the business' website, Facebook page, etc). Waymark will perform a search to analyze this website and create a profile that will inform the script and content used in generated videos. Once a topic is created, it can be re-used as many times as desired, so it is highly recommended to store the created topic's ID and re-use it for video generations in future sessions.

A topic search may take up to 1-2 minutes to complete.

Video Generation Requests

A video generation request is an instruction to the Waymark backend to create a video based on a topic and a set of customization parameters (such as aspect ratio, duration, language, and prompt instructions).

A video generation may take up to 1-2 minutes to complete, but if the generation's topic still has a topic search in progress, the generation will wait in an idle "PENDING" state until the search completes to make sure it has a complete profile of the topic to work with. This means that if you start a topic search and video generation at the same time, the whole process may take a total of 2-4 minutes to complete.

Background Actions APIs

The following public APIs are available for managing background actions:

See the API Reference for full method signatures and usage details.

Best Practices

API Usage Examples

// Assume waymark is an authenticated Waymark instance
const sourceUrl = 'https://example.com/business-page';
const { topicId, requestId } = await waymark.startTopicSearch(sourceUrl);

// Subscribe to search status updates
waymark.subscribeToTopicSearchStatusUpdates(topicId, ({ status, error }) => {
  if (status === 'PROCESSING') {
    // Topic is ready to open in the UI with waymark.openWaymark({ topicId }), but the user may see a brand with incomplete info
    // that will continue streaming in until the search is complete.
  } else if (status === 'COMPLETE') {
    // Topic creation finished
  } else if (status === 'FAILED') {
    // The search failed
    console.error(`The topic search failed with code ${error.code} and message ${error.message}`);
  }
});

Starting a Video Generation Request

// Assume topicId is from a topic search
const videoParams = {
  aspectRatio: '16:9',
  duration: 30,
  topicId,
  language: 'en-US',
  videoInstructions: 'Highlight the main features.',
};
const { requestId, videoId } = await waymark.startVideoGeneration(videoParams);

// Begin polling for status updates
waymark.subscribeToGenerationStatusUpdates(requestId, ({ status, error }) => {
  if (status === 'PROCESSING') {
    // Video is ready to open in the UI with waymark.openWaymark({ generationRequestId }), but the user will see a loading screen
    // until the generation completes.
  } else if (status === 'COMPLETE') {
    // Video generation finished
  } else if (status === 'FAILED') {
    // The generation failed
    console.error(
      `The video generation failed with code ${error.code} and message ${error.message}`,
    );
  }
});

Full Integration Flow Example

// 1. Authenticate the user (see API Reference for details)
await waymark.createAccount(createAccountToken);

// 2. Start a topic search
const { topicId } = await waymark.startTopicSearch('https://example.com/business-page');
// 3. Start a video generation request
const { requestId } = await waymark.startVideoGeneration({
  topicId,
  aspectRatio: '16:9',
  duration: 30,
  language: 'en-US',
  videoInstructions: 'Highlight the main features.',
});

const unsubscribeFromGenerationUpdates = waymark.subscribeToGenerationStatusUpdates(
  requestId,
  ({ status, error }) => {
    if (status === 'PROCESSING') {
      // It is now safe to open the generation in the Waymark UI with `waymark.openWaymark({ generationRequestId: requestId })`
      // The user will see a loading bar until the generation completes
    } else if (status === 'COMPLETE') {
      // The user will now see a video player with a preview of the generated video right away if it is opened in the Waymark UI
    }
  },
);