Prediction Types

API Documentation Reference: Core prediction types conform to the v1 Predictions API. This page documents the TypeScript SDK representation and SDK-specific additions like RunOptions, WaitOptions, and the Prediction class wrapper.

See Predictions for usage.

PredictionRequest

SDK request payload for creating predictions. Maps directly to POST /v1/predictions request body.

interface PredictionRequest {
  model: string;
  input: Record<string, any>;
  await?: boolean;
  stream?: boolean;
  webhook?: Webhook | {
    url: string;
    events: ReadonlyArray<string>;
  };
}

Parameter	Type	Default	Description
`model`	`string`	—	Model slug — see Models.
`input`	`Record<string, any>`	—	Model input parameters (required).
`await`	`boolean`	`false`	When `true`, the API holds the connection until the prediction completes. See Server-Side Wait. Do not use for video models.
`stream`	`boolean`	`false`	Enable streaming output.
`webhook`	`Webhook \| { url, events }`	—	Webhook config — see Webhooks.

RunOptions

SDK-specific type for client.run(). Extends PredictionRequest with client-side polling controls (interval, maxWait, signal).

interface RunOptions {
  input: Record<string, any>;
  webhook?: Webhook | { url: string; events: ReadonlyArray<string> };
  stream?: boolean;
  interval?: number;
  maxWait?: number;
  signal?: AbortSignal;
}

Parameter	Type	Default	Description
`input`	`Record<string, any>`	—	Model input (required).
`webhook`	`Webhook \| { url, events }`	—	Webhook config.
`stream`	`boolean`	`false`	Enable streaming.
`interval`	`number`	`5000`	Polling interval (ms) when used with `onProgress`.
`maxWait`	`number`	—	Max wait time (ms). Throws `WAIT_TIMEOUT`.
`signal`	`AbortSignal`	—	Abort polling. Throws `ABORTED`.

interval, maxWait, and signal only apply when run() is used with an onProgress callback.

WaitOptions

SDK-specific type for client-side polling via client.wait(). Not sent to the API.

interface WaitOptions {
  interval?: number;
  maxWait?: number;
  signal?: AbortSignal;
}

Parameter	Type	Default	Description
`interval`	`number`	`5000`	Poll interval in ms.
`maxWait`	`number`	—	Max wait time (ms).
`signal`	`AbortSignal`	—	Abort signal.

PredictionSdkOptions

SDK-specific options for predictions. Not sent to the API — used for client-side validation and behavior control.

interface PredictionSdkOptions {
  compatibilityCheck?: boolean;
  autoAwait?: boolean;
}

Parameter	Type	Description
`compatibilityCheck`	`boolean`	Validate model slug against the models cache before submitting.
`autoAwait`	`boolean`	(New in v1.0.5) When `true` and `compatibilityCheck: true`, automatically sets `await: true` for image models (causing server-side blocking). Video/audio models ignore this. Explicit `payload.await` always takes priority. See autoAwait.

PredictionResponse

SDK representation of the v1 Prediction object returned from the Predictions API. This TypeScript interface matches the API JSON response exactly — returned by POST /v1/predictions, GET /v1/predictions/:id, and GET /v1/predictions. The SDK performs no transformations; it's a direct mapping of the REST API response.

interface PredictionResponse {
  id: string;
  status: PredictionStatus;
  type: PredictionType;
  stream: boolean;
  input: Record<string, any>;
  output?: string | string[];
  response?: string;
  created_at: string;
  started_at: string;
  completed_at: string;
  updated_at: string;
  privacy: string;
  source?: PredictionSource;
  model?: {
    name: string;
    type: string;
  };
  webhook?: {
    url: string | null;
    events: string[];
  };
  metrics?: {
    image_count?: number;
    predict_time?: number;
    total_time?: number;
    asset_count?: number;
    progress?: number;
  };
  metadata?: {
    billing?: { credits_used: number };
    storage?: {
      files: {
        name: string;
        type: string;
        size: number;
        url: string;
      }[];
    };
    data_available?: boolean;
  };
  urls?: {
    get?: string;
    cancel?: string;
    stream?: string;
    delete?: string;
  };
}

Returned by client.predict() and predictions.create().

Field	Type	Description
`id`	`string`	Unique prediction ID.
`status`	`PredictionStatus`	Current status.
`type`	`PredictionType`	`'inference'` or `'training'`.
`stream`	`boolean`	Whether streaming was requested.
`input`	`Record<string, any>`	Input that was submitted.
`response`	`string`	Raw response text (if applicable).
`output`	`string \| string[]`	Output URL(s) or text.
`created_at`	`string`	ISO 8601 creation timestamp.
`started_at`	`string`	ISO 8601 start timestamp.
`completed_at`	`string`	ISO 8601 completion timestamp.
`updated_at`	`string`	ISO 8601 last update.
`privacy`	`string`	Prediction privacy level.
`source`	`PredictionSource`	`'api'` · `'cli'` · `'web'`.
`model`	`{ name, type }`	Model info.
`webhook`	`{ url, events }`	Webhook that was attached.
`metrics`	`object`	`image_count`, `predict_time`, `total_time`, `asset_count`, `progress`.
`metadata`	`object`	`billing.credits_used`, `storage.files[]`, `data_available`.
`urls`	`object`	`get`, `cancel`, `stream`, `delete` endpoint URLs.

PredictionsListOptions

Query parameters for GET /v1/predictions.

interface PredictionsListOptions {
  page?: number;
  since?: string;
  until?: string;
  model?: string;
}

Passed to predictions.list().

Parameter	Type	Description
`page`	`number`	Page number.
`since`	`string`	Start date filter (ISO 8601 / `YYYY-MM-DD`).
`until`	`string`	End date filter (ISO 8601 / `YYYY-MM-DD`).
`model`	`string`	Filter by model slug.

PaginatedResponse<T>

interface PaginatedResponse<T> {
  data: T[];
  pagination: Pagination;
}

Field	Type	Description
`data`	`T[]`	Page of results.
`pagination`	`Pagination`	Pagination metadata.

Pagination

interface Pagination {
  current_page: number;
  per_page: number;
  total: number;
  last_page: number;
}

Field	Type	Description
`current_page`	`number`	Current page number.
`per_page`	`number`	Items per page.
`total`	`number`	Total item count.
`last_page`	`number`	Last page number.

Prediction Class

SDK-specific wrapper class around PredictionResponse. Provides convenience methods for common operations. Returned exclusively by client.run().

class Prediction {
  readonly id: string;
  readonly status: PredictionStatus;
  readonly output: string | string[] | undefined;
  readonly response: PredictionResponse;
  
  outputs(): string | string[] | undefined;
  raw(): PredictionResponse;
  cancel(): Promise<PredictionResponse>;
  delete(): Promise<PredictionResponse>;
  stream(): Promise<PredictionResponse>;
}

Member	Type	Description
`.id`	`string`	Prediction ID.
`.status`	`PredictionStatus`	Current status.
`.output`	`string \| string[]`	Raw output.
`.response`	`PredictionResponse`	Full API response.
`.outputs()`	`string \| string[]`	Normalized output — unwraps single-element arrays.
`.raw()`	`PredictionResponse`	Full response as plain object.
`.cancel()`	`Promise<PredictionResponse>`	Cancel the prediction.
`.delete()`	`Promise<PredictionResponse>`	Delete the prediction and its assets.
`.stream()`	`Promise<PredictionResponse>`	Get the streaming endpoint.

Prediction Enums

TypeScript enums mirroring the v1 Prediction object string literal types.

enum PredictionStatus {
  PENDING    = 'pending',
  PROCESSING = 'processing',
  SUCCEEDED  = 'succeeded',
  FAILED     = 'failed',
  CANCELLED  = 'cancelled',
  STARTING   = 'starting',
  STARTED    = 'started',
}

enum PredictionType {
  INFERENCE = 'inference',
  TRAINING  = 'training',
}

enum PredictionSource {
  API = 'api',
  CLI = 'cli',
  WEB = 'web',
}

OnProgressCallback

SDK-specific type for polling progress callbacks in client.run().

type OnProgressCallback = (prediction: PredictionResponse) => void

QueueItem

interface QueueItem {
  request: PredictionRequest;
  sdk?: PredictionSdkOptions;
}

Field	Type	Description
`request`	`PredictionRequest`	The queued request.
`sdk`	`PredictionSdkOptions`	SDK options for the request.

SDK Predictions — Complete predictions implementation guide
Predictions API — API documentation for predictions
SDK Errors — Error handling for predictions

How is this guide?

On this page