Predictions API

The client.predictions component provides methods to retrieve, list, and manage predictions across all content types. This is the central hub for tracking the status of all processing jobs in the platform.

Quick Examples

Get a Prediction

import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Retrieve a specific prediction by ID
const prediction = await client.predictions.get("pred_abc123");
console.log(`Status: ${prediction.status}`);

List Predictions

// List recent predictions
const predictions = await client.predictions.list({ limit: 10 });
for (const pred of predictions) {
  console.log(`${pred.id}: ${pred.status}`);
}

Wait for Completion

// Wait for a prediction to complete
const completed = await client.predictions.wait(
  "pred_abc123",
  60,  // Maximum wait time in seconds
  1    // Check interval in seconds
);
console.log(`Completed at: ${completed.completed_at}`);

Core Operations

Retrieving Predictions

Get details about a specific prediction:

import { VlmRun } from "vlmrun";
import type { PredictionResponse } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Get prediction by ID
const prediction: PredictionResponse = await client.predictions.get("pred_abc123");

// Access prediction properties
console.log(`ID: ${prediction.id}`);
console.log(`Status: ${prediction.status}`);
console.log(`Created: ${prediction.created_at}`);

// If completed, access the structured response
if (prediction.status === "completed" && prediction.response) {
  console.log(`Result: ${JSON.stringify(prediction.response)}`);
}

Listing Predictions

List predictions you’ve created (with pagination):

import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Basic listing with default pagination
const predictions = await client.predictions.list();

// Custom pagination
const paginatedPredictions = await client.predictions.list({
  skip: 0,   // Skip this many items
  limit: 10  // Return at most this many items
});

// Process the list
for (const prediction of paginatedPredictions) {
  console.log(`ID: ${prediction.id}, Status: ${prediction.status}`);
}

Waiting for Completion

Wait for long-running predictions to complete:

import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Wait with default settings (60 seconds timeout, 1 second checks)
const completed = await client.predictions.wait("pred_abc123");

// Wait with custom timeout and polling interval
const completedCustom = await client.predictions.wait(
  "pred_abc123",
  300,  // Maximum wait time (5 minutes)
  2     // Check every 2 seconds
);

// Check results after waiting
if (completedCustom.status === "completed") {
  console.log(`Success! Result: ${JSON.stringify(completedCustom.response)}`);
} else {
  console.log(`Failed or timed out: ${completedCustom.status}`);
}

The wait() method will throw a TimeoutError if the prediction doesn’t complete within the specified timeout.

Prediction Statuses

Predictions can have the following statuses:

Status	Description
`enqueued`	The prediction is waiting to be processed
`pending`	The prediction is preparing to start
`running`	The prediction is actively being processed
`completed`	The prediction has completed successfully
`failed`	The prediction encountered an error
`paused`	The prediction has been paused

Feedback Operations

Get Feedbacks for a Prediction

import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Get all feedbacks for a prediction
const feedbacks = await client.predictions.getFeedbacks("pred_abc123");
for (const feedback of feedbacks) {
  console.log(`Feedback ID: ${feedback.id}`);
  console.log(`Notes: ${feedback.notes}`);
}

Create Feedback

import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Create feedback for a prediction
const feedback = await client.predictions.createFeedback({
  request_id: "pred_abc123",
  response: { corrected_field: "new_value" },
  notes: "Corrected the invoice number",
});

console.log(`Feedback created: ${feedback.id}`);

Media-Specific APIs

The base Predictions class is extended by specialized prediction classes for different media types:

Image Predictions

// Generate prediction from image files
const prediction = await client.image.generate({
  images: ["path/to/image.jpg"],  // Local file paths or base64 strings
  domain: "document.invoice"
});

// Generate prediction from image URLs
const predictionFromUrl = await client.image.generate({
  urls: ["https://example.com/image.jpg"],
  domain: "document.invoice"
});

// Generate schema from image
const schema = await client.image.schema({
  images: ["path/to/image.jpg"]
});

Document, Audio, and Video Predictions

These specialized APIs follow a consistent pattern:

// Process a document file
const docPrediction = await client.document.generate({
  fileId: "file_abc123",
  domain: "document.invoice"
});

// Process from a URL
const audioPrediction = await client.audio.generate({
  url: "https://example.com/audio.mp3",
  domain: "audio.transcription"
});

// Process video
const videoPrediction = await client.video.generate({
  fileId: "file_xyz789",
  domain: "video.transcription"
});

Response Structure

The PredictionResponse object includes these key fields:

interface PredictionResponse {
  id: string;                    // Unique prediction identifier
  status: JobStatus;             // Current job status
  created_at: string;            // When the prediction was created
  completed_at?: string;         // When the prediction was completed (if done)
  response?: any;                // Structured result data
  message?: string;              // Status message or error details
  usage?: CreditUsage;           // Usage and billing information
}

The usage field contains a CreditUsage object:

interface CreditUsage {
  elements_processed?: number;   // Number of elements processed
  element_type?: "image" | "page" | "video" | "audio";  // Type of element
  credits_used?: number;         // Credits consumed by the operation
}

Common Patterns

Process and Wait

A common pattern is to start a prediction and wait for it to complete:

import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// 1. Start the prediction
const prediction = await client.document.generate({
  fileId: "file_abc123",
  domain: "document.invoice"
});

// 2. Wait for completion if needed
let result = prediction;
if (prediction.status !== "completed") {
  try {
    result = await client.predictions.wait(
      prediction.id,
      120  // Wait up to 2 minutes
    );
  } catch (error) {
    console.log("Processing is taking longer than expected");
    // Handle timeout case
  }
}

// 3. Process the results
if (result.status === "completed") {
  const formData = result.response;
  console.log(`Form data: ${JSON.stringify(formData)}`);
}

Batch Processing

For batch operations, use the batch parameter and track multiple predictions:

import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Start multiple predictions in batch mode
const predictionIds: string[] = [];
const fileIds = ["file_1", "file_2", "file_3"];

for (const fileId of fileIds) {
  const prediction = await client.document.generate({
    fileId,
    domain: "document.invoice",
    batch: true  // Process asynchronously
  });
  predictionIds.push(prediction.id);
}

console.log(`Started ${predictionIds.length} predictions`);

// Wait for all to complete
const results = await Promise.all(
  predictionIds.map(id => client.predictions.wait(id, 300))
);

console.log("All predictions complete!");

Error Handling

Implement robust error handling:

import { VlmRun, ApiError } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

try {
  // Start prediction
  const prediction = await client.document.generate({
    fileId: "file_abc123",
    domain: "document.invoice"
  });

  // Wait for completion
  const result = await client.predictions.wait(prediction.id);

  // Check for success
  if (result.status === "completed") {
    console.log("Processing successful!");
    console.log(result.response);
  } else {
    console.log(`Processing failed: ${result.status}`);
    console.log(`Message: ${result.message}`);
  }

} catch (error) {
  if (error instanceof ApiError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status: ${error.http_status}`);
  } else if (error instanceof Error && error.name === "TimeoutError") {
    console.error("Prediction timed out");
  } else {
    console.error(`Unexpected error: ${error}`);
  }
}

TypeScript Interfaces

interface ListParams {
  skip?: number;
  limit?: number;
}

interface FeedbackParams {
  request_id: string;
  response?: Record<string, any>;
  notes?: string;
}

interface FeedbackResponse {
  id: string;
  created_at: string;
  request_id: string;
  response: any;
  notes?: string;
}

Best Practices

Efficient Polling

Use appropriate intervals when waiting for predictions:

// For quick predictions (e.g., simple image classification)
const quickResult = await client.predictions.wait(
  predictionId,
  30,  // 30 seconds
  1    // Check every second
);

// For complex processing (e.g., large documents, long videos)
const complexResult = await client.predictions.wait(
  predictionId,
  600,  // 10 minutes
  5     // Check every 5 seconds
);

Using Callbacks for Long-Running Jobs

For very long-running predictions, consider using callback URLs:

const prediction = await client.video.generate({
  fileId: "file_abc123",
  domain: "video.transcription",
  batch: true,
  callbackUrl: "https://your-server.com/webhook/predictions"
});

// Your webhook will receive the completed prediction
console.log(`Prediction started: ${prediction.id}`);

​Predictions API

​Quick Examples

​Get a Prediction

​List Predictions

​Wait for Completion

​Core Operations

​Retrieving Predictions

​Listing Predictions

​Waiting for Completion

​Prediction Statuses

​Feedback Operations

​Get Feedbacks for a Prediction

​Create Feedback

​Media-Specific APIs

​Image Predictions

​Document, Audio, and Video Predictions

​Response Structure

​Common Patterns

​Process and Wait

​Batch Processing

​Error Handling

​TypeScript Interfaces

​Best Practices

​Efficient Polling

​Using Callbacks for Long-Running Jobs