Skip to main content

Models

A model is a Marketplace asset, such as an LLM, a speech recognizer or a translator, that you run directly or give to an agent.

Every model has the same interface: get it by asset path, call run(), and read result.data. To swap models, change the path.

Try it​

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

model = aix.Model.get("openai/gpt-4o-mini/openai")
result = model.run(text="Why did the chicken cross the road? One sentence.")
print(result.data)
Show output

Find a model​

Search by keyword and filter by host or developer. Browse the same catalog in the Marketplace.

page = aix.Model.search(query="gpt", host="openai", page_size=5)
for model in page.results:
    print(model.name, model.path)
print(page.total)
Show output
ParameterTypeDefaultDescription
querystrNoneKeyword matched against the name and description.
hoststrNoneWhere the model is served, for example "openai".
developerstrNoneWho built the model, for example "Meta". Case-sensitive.
page_sizeint20Results per page. The page also has total, page_number and page_total.

Get a model​

Get a model by its asset path or its asset ID. The path is easier to read; both return the same model.

model = aix.Model.get("openai/gpt-4o-mini/openai")
print(model.name, model.id, model.host)

model = aix.Model.get("669a63646eb56306647e1091")
print(model.name, model.path)
Show output

Stream the output​

Use run_stream() to print text as the model generates it. Check model.supports_streaming first.

with model.run_stream(text="Tell me a two-sentence story about a robot.") as stream:
    for chunk in stream:
        print(chunk.data, end="", flush=True)
Show output

Each chunk has data (the new text) and status. The last chunk has empty data and carries token counts in usage. model.run(text="...", stream=True) returns the same chunks.

Run without waiting​

run_async() returns at once with a polling URL. Poll it until the result is complete.

import time

start = model.run_async(text="Summarize the history of computing in two sentences.")

while True:
    result = model.poll(start.url)
    if result.completed:
        break
    time.sleep(2)

print(result.data)
Show output

To run many prompts in parallel, start each with run_async() and poll the URLs together.

Set parameters​

Set parameters on model.inputs before you call run(). Dot notation, dict notation and update() all set the same values.

model.inputs.temperature = 0.3
model.inputs["max_tokens"] = 200
model.inputs.update(temperature=0.2, max_tokens=150)

result = model.run(text="Write a one-sentence product description for a smartwatch.")
print(result.data)
print(result.usage.completion_tokens)
Show output

Parameters differ by model. Setting one the model does not have raises AttributeError: Input 'top_p' not found, and an out-of-range value fails at run time with err.validation_error.

Inspect and reset parameters​

List a model's parameters and their current values, then reset one or all of them to the model's defaults.

print(model.inputs.keys())
print(model.inputs.required)

model.inputs.reset("temperature")
model.inputs.reset()
print(dict(model.inputs.items()))
Show output

Get the provider's raw output​

Pass options={"includeRawData": True} to get the provider's full response next to the normalized result. Its shape depends on the provider.

result = model.run(text="Say hello.", options={"includeRawData": True})
print(result.data)
print(list(result._raw_data["rawData"].keys()))
Show output

Over REST, add "options": {"includeRawData": true} to the request body and read the top-level rawData field.

Use a model in an agent​

Pass a model as llm to make it the agent's reasoning model.

llm = aix.Model.get("openai/gpt-4o-mini/openai")

agent = aix.Agent(
    name="Study assistant",
    description="Explains machine learning concepts.",
    instructions="Answer in two sentences.",
    llm=llm,
).save()

result = agent.run("What is the difference between supervised and unsupervised learning?")
print([step["unit"]["name"] for step in result.data.steps])
print(result.data.output)
Show output

To give an agent a model as a tool, pass it in tools, for example tools=[aix.Model.get("google/cloud-translation/google")]. Delete the agent with agent.delete() when you are done.

Other model types​

Non-LLM models take their own inputs. A translation model takes the text and two language codes:

translator = aix.Model.get("google/cloud-translation/google")

result = translator.run(text="Hello, how are you?", sourcelanguage="en", targetlanguage="es")
print(result.data)
Show output

Speech, image and video models read media from a URL. For a local file, upload it first with FileUploader and pass the returned URL. This transcribes a local recording with Whisper Large:

from aixplain.v2 import FileUploader

audio_url = FileUploader(api_key=aix.api_key).upload(
    file_path="greeting.wav",
    is_temp=True,
    return_download_link=True,
)

whisper = aix.Model.get("66311fda6eb563279c574b71")  # Whisper Large
result = whisper.run(source_audio=audio_url, sourcelanguage="en")
print(result.data)
Show output

Whisper detects the spoken language itself; the SDK requires sourcelanguage, but its value does not change the result. Over HTTP, see Upload a file.

Troubleshooting​

SymptomCauseFix
APIError: Not Found on Model.get()The path or ID does not exist, or the model was retiredFind the current path with aix.Model.search()
AttributeError: Input '...' not foundThe model does not have that parameterList the model's parameters with model.inputs.keys()
err.validation_error: Invalid value for ...The value is outside the model's rangeUse a value the model's Marketplace card allows
ValueError: Required parameter '...' is missingThe model needs another input, such as sourcelanguageCheck model.inputs.required

Next steps​