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. The names of the output columns are prefixed by the model name if there are multiple models, otherwise the prefix is ommitted.

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