Jobs

This section describes how to manage jobs with the Swiftia API. A "job" represents a unit of work submitted to Swiftia for processing, such as generating short-form videos.

Asynchronous Job Processing

Jobs submitted to the Swiftia API are processed asynchronously. This means that the API returns immediately after you create a job, even if the job takes a long time to complete. This prevents your application from blocking while waiting for the results.

Job Lifecycle

1. Create a Job: Submit a request to the /api/jobs endpoint to create a new job, specifying the desired function and parameters in the request body.
2. Monitor Job Status: Retrieve the job status periodically to track its progress using the /api/jobs/{jobId} endpoint.
3. Retrieve Results: Once the job is complete, retrieve the results (e.g., generated shorts, transcription data) using the /api/jobs/{jobId} endpoint.
4. Render Output (If Applicable): Some functions, like VideoShorts, may require a separate rendering step to generate the final output (e.g., an MP4 file). See the POST/GET render section for details.

Creating a Job

Send a POST request to /api/jobs to create a new job. The request body should contain a JSON object with the following fields:

• functionName (string, required): The name of the function to execute (e.g., VideoShorts).
• youtubeVideoId (string, required): The ID or URL of the YouTube video to process.
• options (object, optional): An object containing additional options for the function. For the VideoShorts function, this includes the predefinedShorts option.
• webhook (string, optional): A URL to receive a webhook notification upon job completion.

Retrieving Job Status / Results:

Use the /api/jobs/{jobId} endpoint with a GET request to retrieve the status and, upon completion, the results of a job.

Common Response Fields

The following fields are common to job-related responses:

• jobId (string): A unique identifier for the job.
• status (string): The current status of the job (e.g., PROCESSING, COMPLETED, FAILED).
• createdAt (string): The timestamp when the job was created (ISO 8601 format).
• error (object): (Only in error responses) Details about the error. See Error Handling.

Example Request (Creating a Job - VideoShorts):

POST /api/jobs

{
  "functionName": "VideoShorts",
  "youtubeVideoId": "YOUR_VIDEO_ID",
  "options": { 
    "predefinedShorts": [
       // ... predefined shorts options
    ]
  },
  "webhook": "YOUR_WEBHOOK_URL"
}

Example Response (Job Created):

{
  "jobId": "NEWLY_CREATED_JOB_ID"
}

Example Request (Retrieving Job Status/Results):

GET /api/jobs/YOUR_JOB_ID