predictions module

Predictions module.

class ErrorSource(StrEnum)

Bases: StrEnum

Enumeration of possible error sources.

internal = 'internal'

external = 'external'

class Status(StrEnum)

Bases: StrEnum

Enumeration of possible prediction statuses.

PENDING = 'pending'

STARTING = 'starting'

STARTED = 'started'

FAILED = 'failed'

SUCCEEDED = 'succeeded'

CANCELLED = 'cancelled'

ABANDONED = 'abandoned'

class PredictionPaginationOptions

Bases: PaginationOptions

Pagination options for querying predictions.

statuses : NotRequired[list[Status]]

The list of statuses to filter predictions by.

cursor : NotRequired[str]

page_size : NotRequired[int]

class TaskError

Bases: TypedDict

Represents an error that occurred during a prediction.

source : ErrorSource

message : str

detail : JsonValue

class PredictionModel

Bases: TypedDict

Represents the prediction model.

owner : str

Name of the model’s owner.

name : str

Name of the model.

version_number : int

Version number of the model.

class Prediction

Bases: TypedDict

Represents a prediction.

id : str

Unique identifier for the prediction.

created_at : str

Timestamp when the prediction was created.

status : Status

Current status of the prediction.

updated_at : str

Timestamp of the last update to the prediction.

setup_time : str | None

Time taken to set up the prediction environment.

execution_time : str | None

Time taken to execute the prediction.

model : PredictionModel

The model of the prediction.

class PredictionWithDetails

Bases: Prediction

Represents a prediction with details.

input : Mapping[str, JsonValue]

Input data provided for the prediction.

output : JsonValue

Output generated by the prediction.

error : TaskError | None

Error details if the prediction failed.

metrics : Mapping[str, JsonValue] | None

Usage metrics returned by the model.

stream : bool

Whether the prediction supports streaming. This value may change to false if streaming is no longer available for the prediction,such as after it has expired.

id : str

created_at : str

status : Status

updated_at : str

setup_time : str | None

execution_time : str | None

model : PredictionModel

class Webhook

Bases: TypedDict

Represents webhook details.

url : str

HTTP URL to POST updates to.

secret : NotRequired[str | None]

Secret to generate the signature for the webhook.

class CreatePredictionParams

Bases: TypedDict

Prediction creation params.

model : str

The model reference in either owner/name or owner/name:version-number format (for example: deepseek-ai/deepseek-r1 or deepseek-ai/deepseek-r1:1).

• Type: model

input : Mapping[str, JsonValueWithFile]

Input data provided for the prediction.

webhook : NotRequired[Webhook | None]

Details about the webhook to post prediction updates to.

validate_input : NotRequired[bool]

Enable input validation against the schema before processing.

class WaitOptions(poll_interval=1.0, on_poll=None)

Bases: _BaseWaitOptions

Options for customizing wait behaviour.

• Parameters:
  • poll_interval (float)
  • on_poll (Callable[[PredictionWithDetails], None] | None)

on_poll : Callable[[PredictionWithDetails], None] | None = None

Optional callback that receives the latest prediction after each poll.

poll_interval : float = 1.0

Time in seconds between polling attempts to check the prediction status.

class AsyncWaitOptions(poll_interval=1.0, on_poll=None)

Bases: _BaseWaitOptions

Options for customizing asynchronous wait behaviour.

• Parameters:
  • poll_interval (float)
  • on_poll (Callable[[PredictionWithDetails], Awaitable[None]] | None)

on_poll : Callable[[PredictionWithDetails], Awaitable[None]] | None = None

Optional callback that receives the latest prediction after each poll.

poll_interval : float = 1.0

Time in seconds between polling attempts to check the prediction status.

class CreateWaitOptions(duration=None, poll=True, poll_interval=1.0, on_poll=None)

Bases: WaitOptions, _BaseCreateWaitOptions

Options for customizing wait behaviour when creating a prediction.

• Parameters:
  • duration (float | None)
  • poll (bool)
  • poll_interval (float)
  • on_poll (Callable[[PredictionWithDetails], None] | None)

duration : float | None = None

Max seconds the server holds the connection open while waiting for the prediction to finish. None uses the server’s default.

If the prediction is created with stream=True, this is instead the maximum time in seconds the server waits between events before closing an idle connection. It only limits the idle time between events and is not a wait for the prediction to finish. After an idle close, the client reconnects with the same value.

on_poll : Callable[[PredictionWithDetails], None] | None = None

Optional callback that receives the latest prediction after each poll.

poll : bool = True

If the prediction isn’t finished when the server responds, keep polling until it reaches a terminal state. If False, return it as is, which may not be terminal. Ignored when the prediction is created with stream=True.

poll_interval : float = 1.0

Time in seconds between polling attempts to check the prediction status.

class AsyncCreateWaitOptions(duration=None, poll=True, poll_interval=1.0, on_poll=None)

Bases: AsyncWaitOptions, _BaseCreateWaitOptions

Options for customizing wait behaviour when creating a prediction.

• Parameters:
  • duration (float | None)
  • poll (bool)
  • poll_interval (float)
  • on_poll (Callable[[PredictionWithDetails], Awaitable[None]] | None)

duration : float | None = None

Max seconds the server holds the connection open while waiting for the prediction to finish. None uses the server’s default.

If the prediction is created with stream=True, this is instead the maximum time in seconds the server waits between events before closing an idle connection. It only limits the idle time between events and is not a wait for the prediction to finish. After an idle close, the client reconnects with the same value.

on_poll : Callable[[PredictionWithDetails], Awaitable[None]] | None = None

Optional callback that receives the latest prediction after each poll.

poll : bool = True

If the prediction isn’t finished when the server responds, keep polling until it reaches a terminal state. If False, return it as is, which may not be terminal. Ignored when the prediction is created with stream=True.

poll_interval : float = 1.0

Time in seconds between polling attempts to check the prediction status.

DEFAULT_WAIT_OPTIONS = WaitOptions(poll_interval=1.0, on_poll=None)

Default wait options.

DEFAULT_ASYNC_WAIT_OPTIONS = AsyncWaitOptions(poll_interval=1.0, on_poll=None)

Default async wait options.

DEFAULT_CREATE_WAIT_OPTIONS = CreateWaitOptions(duration=None, poll=True, poll_interval=1.0, on_poll=None)

Default wait options for prediction creation.

DEFAULT_ASYNC_CREATE_WAIT_OPTIONS = AsyncCreateWaitOptions(duration=None, poll=True, poll_interval=1.0, on_poll=None)

Default async wait options for prediction creation.

class PredictionStreamEventType(StrEnum)

Bases: StrEnum

Enumeration of possible prediction stream event types.

INIT = 'init'

OUTPUT = 'output'

ERROR = 'error'

DONE = 'done'

class PredictionStreamEvent

Bases: TypedDict

An event from a prediction’s stream.

id : str

The event ID.

event : PredictionStreamEventType

The event type.

data : JsonValue

The event data.

class Predictions(api, files)

Bases: Resource

Initializes the Predictions resource.

• Parameters:
  • api (API) – An instance of the API class.
  • files (Files) – An instance of the Files class.

get(prediction_id)

Get a prediction by id.

• Parameters: prediction_id (str) – The unique identifier of the prediction.
• Returns: The prediction object.
• Return type: PredictionWithDetails

async async_get(prediction_id)

Get a prediction by id.

• Parameters: prediction_id (str) – The unique identifier of the prediction.
• Returns: The prediction object.
• Return type: PredictionWithDetails

cancel(prediction_id)

Cancel a prediction by id.

• Parameters: prediction_id (str) – The unique identifier of the prediction.
• Return type: None

async async_cancel(prediction_id)

Cancel a prediction by id.

• Parameters: prediction_id (str) – The unique identifier of the prediction.
• Return type: None

list(pagination_options=None)

List predictions.

• Parameters: pagination_options (PredictionPaginationOptions | None) – Optional settings to control pagination behaviour.
• Returns: Paginated response containing predictions and navigation metadata.
• Return type: PaginatedResponse[Prediction]

async async_list(pagination_options=None)

List predictions.

• Parameters: pagination_options (PredictionPaginationOptions | None) – Optional settings to control pagination behaviour.
• Returns: Paginated response containing predictions and navigation metadata.
• Return type: PaginatedResponse[Prediction]

create(wait: Literal[True], stream: Literal[True], wait_options: CreateWaitOptions = DEFAULT_CREATE_WAIT_OPTIONS, **params: Unpack[CreatePredictionParams]) → Generator[PredictionStreamEvent, None, None]

create(wait: bool = False, stream: Literal[False] = False, wait_options: CreateWaitOptions = DEFAULT_CREATE_WAIT_OPTIONS, **params: Unpack[CreatePredictionParams]) → PredictionWithDetails

create(wait: Literal[False] = False, stream: bool = False, wait_options: CreateWaitOptions = DEFAULT_CREATE_WAIT_OPTIONS, **params: Unpack[CreatePredictionParams]) → PredictionWithDetails

create(wait: bool = False, stream: bool = False, wait_options: CreateWaitOptions = DEFAULT_CREATE_WAIT_OPTIONS, **params: Unpack[CreatePredictionParams]) → PredictionWithDetails | Generator[PredictionStreamEvent, None, None]

Create a prediction.

Files in the input are uploaded concurrently before the prediction is created.

When events are streamed, the returned generator holds the connection open. To stop early and release it immediately, wrap the call in contextlib.closing(…).

• Parameters:
  • wait – If True, waits for the prediction to finish, as configured by wait_options. If False, returns the prediction immediately. Defaults to False.
  • stream – Whether to enable streaming. If True and wait is True, returns a generator of the prediction’s events. If the server closes an idle connection, it resumes automatically from the last event received. If True and wait is False, returns the prediction, and its events can be read later with stream(). Defaults to False.
  • wait_options – Options for customizing wait behavior. If not provided, default options are used. Only used when wait is True.
  • params – Prediction creation params.
• Returns: The new prediction, or a generator of its events when events are streamed.

async async_create(wait: Literal[True], stream: Literal[True], wait_options: AsyncCreateWaitOptions = DEFAULT_ASYNC_CREATE_WAIT_OPTIONS, **params: Unpack[CreatePredictionParams]) → AsyncGenerator[PredictionStreamEvent, None]

async async_create(wait: bool = False, stream: Literal[False] = False, wait_options: AsyncCreateWaitOptions = DEFAULT_ASYNC_CREATE_WAIT_OPTIONS, **params: Unpack[CreatePredictionParams]) → PredictionWithDetails

async async_create(wait: Literal[False] = False, stream: bool = False, wait_options: AsyncCreateWaitOptions = DEFAULT_ASYNC_CREATE_WAIT_OPTIONS, **params: Unpack[CreatePredictionParams]) → PredictionWithDetails

async async_create(wait: bool = False, stream: bool = False, wait_options: AsyncCreateWaitOptions = DEFAULT_ASYNC_CREATE_WAIT_OPTIONS, **params: Unpack[CreatePredictionParams]) → PredictionWithDetails | AsyncGenerator[PredictionStreamEvent, None]

Create a prediction.

Files in the input are uploaded concurrently before the prediction is created.

When events are streamed, the returned async generator holds the connection open. To stop early and release it immediately, wrap the awaited call in contextlib.aclosing(…).

• Parameters:
  • wait – If True, waits for the prediction to finish, as configured by wait_options. If False, returns the prediction immediately. Defaults to False.
  • stream – Whether to enable streaming. If True and wait is True, returns an async generator of the prediction’s events. If the server closes an idle connection, it resumes automatically from the last event received. If True and wait is False, returns the prediction, and its events can be read later with async_stream(). Defaults to False.
  • wait_options – Options for customizing wait behavior. If not provided, default options are used. Only used when wait is True.
  • params – Prediction creation params.
• Returns: The new prediction, or an async generator of its events when events are streamed.

wait(prediction_id, options=WaitOptions(poll_interval=1.0, on_poll=None))

Wait for a prediction to complete.

This method uses short polling to check the prediction status at regular intervals until it reaches a terminal state. It blocks execution and waits until the prediction has finished processing.

• Parameters:
  • prediction_id (str) – Unique identifier of the prediction.
  • options (WaitOptions) – Options for customizing wait behavior. If not provided, default options are used.
• Returns: Prediction after completion.
• Return type: PredictionWithDetails

async async_wait(prediction_id, options=AsyncWaitOptions(poll_interval=1.0, on_poll=None))

Wait for a prediction to complete.

This method uses short polling to check the prediction status at regular intervals until it reaches a terminal state. It blocks execution and waits until the prediction has finished processing.

• Parameters:
  • prediction_id (str) – Unique identifier of the prediction.
  • options (AsyncWaitOptions) – Options for customizing wait behavior. If not provided, default options are used.
• Returns: Prediction after completion.
• Return type: PredictionWithDetails

stream(prediction_id, after_id=None, wait=None)

Streams a prediction’s events until it terminates.

Yields events until a terminal event, then stops. When the server closes an idle connection, reconnects automatically from the last seen event. Network errors are raised; to resume, call again with after_id set to the last event’s ID.

To stop early and release the connection immediately, wrap the call in contextlib.closing(…).

• Parameters:
  • prediction_id (str) – The ID of the prediction.
  • after_id (str | None) – Only stream events after this event ID. If None, starts from the first event.
  • wait (float | None) – Maximum time in seconds the server waits between events before closing an idle connection. This only limits the idle time between events. It is not a wait for the prediction to finish, as in wait(). After an idle close, the stream reconnects with the same value. If None, the server’s default is used.
• Yields: The prediction’s events.
• Return type: Generator[PredictionStreamEvent, None, None]

async async_stream(prediction_id, after_id=None, wait=None)

Streams a prediction’s events until it terminates.

Yields events until a terminal event, then stops. When the server closes an idle connection, reconnects automatically from the last seen event. Network errors are raised; to resume, call again with after_id set to the last event’s ID.

To stop early and release the connection immediately, wrap the call in contextlib.aclosing(…).

• Parameters:
  • prediction_id (str) – The ID of the prediction.
  • after_id (str | None) – Only stream events after this event ID. If None, starts from the first event.
  • wait (float | None) – Maximum time in seconds the server waits between events before closing an idle connection. This only limits the idle time between events. It is not a wait for the prediction to finish, as in async_wait(). After an idle close, the stream reconnects with the same value. If None, the server’s default is used.
• Yields: The prediction’s events.
• Return type: AsyncGenerator[PredictionStreamEvent, None]