Model | Mixtrain Docs

from mixtrain import Model

Constructor

Model(name: str)

Creates a reference to an existing model. This is a lazy operation - no API call is made until you access properties or call methods.

Parameter	Type	Description
`name`	`str`	Model name or ID

model = Model("hunyuan-video")

Properties

Property	Type	Description
`name`	`str`	Model name
`source`	`str`	Model source for external models
`description`	`str`	Model description
`metadata`	`dict`	Full metadata dictionary (cached)
`runs`	`list`	Recent runs (cached)

Methods

run()

Run synchronously. Blocks until completion.

model.run(inputs: dict, sandbox: dict = None) -> RunResult

Parameter	Type	Description
`inputs`	`dict`	Input data
`sandbox`	`dict`	Optional sandbox configuration overrides (GPU, memory, timeout, etc.)

Returns: RunResult

result = model.run({"prompt": "A cat playing piano"})
print(result.video.url)
print(result.status)  # "completed"

submit()

Run asynchronously. Returns immediately.

model.submit(inputs: dict, sandbox: dict = None) -> dict

Parameter	Type	Description
`inputs`	`dict`	Input data
`sandbox`	`dict`	Optional sandbox configuration overrides (GPU, memory, timeout, etc.)

Returns: dict with run_number and metadata

run_info = model.submit({"prompt": "A dog running"})
print(f"Started run #{run_info['run_number']}")

Parameter	Type	Description
`limit`	`int`	Maximum number of runs to return

Parameter	Type	Description
`run_number`	`int`	Run number

Parameter	Type	Description
`run_number`	`int`	Run number (defaults to latest)

list_files()

List all files in the model.

model.list_files() -> list[dict]

Returns: list[dict] file information (path, size, modified)

Parameter	Type	Description
`file_path`	`str`	Path to file within model

update()

Update model metadata.

model.update(description: str = None, **kwargs) -> None

Parameter	Type	Description
`description`	`str`	New description

delete()

Delete the model.

model.delete() -> None

refresh()

Clear cached data.

model.refresh() -> None

Class Methods

Model.exists()

Check if a model exists.

Model.exists(name: str) -> bool

Parameter	Type	Description
`name`	`str`	Model name to check

Returns: bool - True if the model exists, False otherwise

if not Model.exists("my-model"):
    Model.create("my-model", file_paths=["model.py"])

Model.batch()

Run multiple models on multiple inputs.

Model.batch(
    models: list[str],
    inputs: list[dict] | Dataset | DataFrame | Series,
    sandbox: dict | None = None,
    max_in_flight: int = 50,
    error_col: str | None = None,
    input_columns: list[str] | None = None
) -> Dataset

Parameter	Type	Description
`models`	`list[str]`	List of model names
`inputs`	`list[dict]` \| `Dataset` \| `DataFrame` \| `Series`	Inputs for each run. Accepts a list of dicts, a mixtrain Dataset (each row becomes an input dict), a pandas DataFrame (each row becomes an input dict), or a pandas Series (column name becomes the input key).
`sandbox`	`dict \| None`	Optional sandbox configuration overrides (GPU, memory, timeout, etc.) applied to all runs
`max_in_flight`	`int`	Maximum concurrent pending requests (default: 50)
`error_col`	`str \| None`	By default, rows where any model failed are dropped (the count is logged). Pass a column name (e.g. `"model_errors"`) to keep every row and record failures in one string column of that name
`input_columns`	`list[str] \| None`	Submit only these columns to the models. All other input columns are carried through to the result unchanged, aligned by row (including through failed-row drops) — e.g. ground-truth labels or row ids. Works for every `inputs` form.

Returns: A Dataset with the submitted input columns plus typed output columns. A model with a single output gets one column named after the model; a model returning multiple outputs gets one typed column per output key.

results = Model.batch(
    models=["flux-pro", "stable-diffusion-xl"],
    inputs=[{"prompt": "a cat"}, {"prompt": "a dog"}],
    max_in_flight=50
)

# Use any Dataset operation
df = results.to_pandas()
results.save("saved-batch-results")

# Keep failed rows and inspect what went wrong
results = Model.batch(["flux-pro"], inputs, error_col="model_errors")
failed = results.filter("model_errors != None")

# Apply sandbox overrides to every run, e.g. pin the mixtrain version
results = Model.batch(
    ["flux-pro"],
    inputs,
    sandbox={"mixtrain_version": "0.4.1"},
)

# Dataset input: submit only the model's input columns other columns
# are carried through to the result, aligned by row.
results = Model.batch(
    ["baseline_vlm", "candidate_vlm"],
    Dataset("vqa-eval-set"),
    input_columns=["image", "question"],
)

Pandas integration:

import pandas as pd
df = pd.DataFrame({"prompt": ["a cat", "a dog", "a bird"]})

# Series — column name "prompt" becomes the input key automatically
results = Model.batch(["flux-pro"], df["prompt"])

# DataFrame — each row becomes an input dict (useful for multi-input models)
results = Model.batch(["flux-pro"], df[["prompt", "seed"]])

RunResult

Return type from model.run() and workflow.run() (and thus routine runs) — one wrapper for every run kind.

Properties

Property	Type	Description
`name`	`str \| None`	Name of the resource (model or workflow) that produced this result
`status`	`str`	`"completed"`, `"failed"`, `"pending"`
`run_number`	`int`	Run number
`output`	`Any`	The value the run
`error`	`str \| None`	Error message if failed

Typed Accessors

Accessor	Type	Description
`video`	`Video \| None`	Video output with `.url`, `.width`, `.height`, `.duration_seconds`
`image`	`Image \| None`	Image output with `.url`, `.width`, `.height`
`audio`	`Audio \| None`	Audio output with `.url`, `.duration_seconds`
`text`	`str \| None`	Text output

result = model.run({"prompt": "Generate a video"})

if result.video:
    print(result.video.url)
    print(result.video.duration_seconds)

if result.image:
    print(result.image.url)
    print(result.image.width, result.image.height)

Raw access

json() returns the whole run as a plain dict It includes status, run_number, error, and the raw outputs:

raw = result.json()
raw["status"]
raw["outputs"]

list_models()

List all models in the workspace.

from mixtrain import list_models

models = list_models()
for m in models:
    print(f"{m.name}: {m.source}")

Constructor

Properties

Methods

run()

submit()

get_runs()

get_run()

get_logs()

list_files()

get_file()

update()

delete()

refresh()

Class Methods

Model.exists()

Model.batch()

RunResult

Properties

Typed Accessors

Raw access

list_models()

On this page