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, processing audio, or any other AI-powered task.

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 using the /api/jobs/{jobId} endpoint.
4. Render Output (If Applicable): Some functions may require a separate rendering step to generate the final output (e.g., an MP4 file, processed audio, etc.). See the Rendering section for details.

Prerequisites and Validation

Before creating a job, the API performs several validation checks:

Storage Validation

The API validates that your organization has sufficient storage space before allowing job creation. If storage is insufficient, the API returns a 403 Forbidden error with detailed storage information.

Storage Error Response:

{
  "error": "fullStorage",
  "message": "Insufficient storage space. Please upgrade your plan or delete some files to create new jobs.",
  "storageInfo": {
    "usedSize": 950,
    "totalSize": 1000,
    "availableSize": 50
  }
}

Phone Verification

If phone verification is enabled for your organization, you must verify your phone number before creating jobs. Unverified users will receive a 403 Forbidden error.

Phone Verification Error Response:

{
  "error": "Phone verification required",
  "message": "Please verify your phone number before creating jobs",
  "phoneNumber": "+1234567890"
}

Credit Validation

The API checks that you have sufficient credits to process the requested job. Insufficient credits will result in a 403 Forbidden error.

Credit Validation Error Response:

{
  "error": "noEnoughCredit",
  "message": "Insufficient credits to process this job"
}

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, AudioProcessor, etc.).
• options (object, optional): An object containing additional options specific to the function being executed.
• webhook (string, optional): A URL to receive a webhook notification upon job completion.

Note: Additional required parameters depend on the specific function. For example, video processing functions might require youtubeVideoId or fileUrl, while audio functions might require different parameters.

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:

• id (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)

POST /api/jobs

{
  "functionName": "FUNCTION_NAME",
  "options": { 
    // Function-specific options
  },
  "webhook": "YOUR_WEBHOOK_URL"
}

Example Response (Job Created)

{
  "id": "NEWLY_CREATED_JOB_ID"
}

Example Request (Retrieving Job Status/Results)

GET /api/jobs/YOUR_JOB_ID

Storage Management

Checking Storage Usage

You can check your organization's current storage usage by making a GET request to the /api/uploads endpoint:

GET /api/uploads

Response:

{
  "subSize": 1000,
  "usedSize": 750.5,
  "usedSizePercent": 75.05,
  "files": [
    // Array of file objects
  ]
}

Storage Limits by Plan

Storage limits vary by your subscription plan:

• Free Plan: 100 MB
• Pro Plan: 1,000 MB (1 GB)
• Swift Plan: 10,000 MB (10 GB)

Managing Storage

To free up storage space:

1. Delete unused files through the file manager or API
2. Upgrade your plan for more storage capacity
3. Contact support for enterprise storage options

Automatic Job Archiving

Your organization can configure automatic job archiving to automatically clean up storage. When jobs are automatically archived after the configured duration:

• The job becomes inaccessible via the API
• All associated files (videos, shorts, transcriptions) are permanently deleted from storage
• Storage space is automatically freed up

Auto-Archive Duration Configuration:

• Default duration: 90 days (jobs older than 90 days are automatically archived)
• Maximum duration: 180 days (6 months)
• Minimum duration: 1 day

Important:

• Auto-archive duration can be configured per organization
• Configuration must be done through the application's organization settings
• It is not possible to set or edit the auto-archive duration via the API
• To configure auto-archiving, navigate to your organization settings in the web application
• If not explicitly configured, the default duration of 90 days applies to all organizations

Function-Specific Documentation

For detailed information about specific functions and their parameters, see the Functions section.