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:

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

POST /api/jobs

{
  "functionName": "FUNCTION_NAME",
  "options": { 
    // Function-specific 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

Storage Management

Checking Storage Usage

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

GET /api/uploads?organizationId=YOUR_ORGANIZATION_ID

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

Function-Specific Documentation

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