Predictions API

client.predictions gets, lists, and waits on predictions for every content type.

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

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

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

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}`);
}

wait() throws TimeoutError when the prediction does not finish before the timeout.

Prediction 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

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

// 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

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
}

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

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

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

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

// 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

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}`);

Overview

SDKs

CLI

CLI - Gateway

CLI - Orion

client.predictions

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

​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

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