Skip to main content

REST API

Call any aixplain agent, model or tool over HTTP with your API key, from any language.

The Python tabs use the SDK, which wraps the same endpoints. To connect from an MCP client instead, see MCP servers.

Authentication​

Send your API key in the x-api-key header. Requests with a body also need Content-Type: application/json.

x-api-key: YOUR_API_KEY
Content-Type: application/json

Use the workspace API key from the aixplain app, and keep it on your server, never in browser code. Every request counts toward your workspace's Rate limiting.

How execution works​

Fast models return the result in the POST response, with "completed": true. Agents and slow models, such as video generation, return a polling URL in data instead:

{
    "status": "IN_PROGRESS",
    "completed": false,
    "data": "https://models.aixplain.com/api/v1/data/<REQUEST_ID>"
}
FieldMeaning
statusIN_PROGRESS, SUCCESS or FAILED.
completedfalse while running, true once finished.
dataWhile running, the URL to poll. Once finished, the result.

GET the URL in data every few seconds until completed is true. Poll the exact URL you receive, because the host and version differ by service.

Run an asset​

Pick a language once; the tabs stay in sync across the page.

Agents​

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

AGENT_ID = "YOUR_AGENT_ID"  # from agent.id
agent = aix.Agent.get(AGENT_ID)
result = agent.run("What is 5 + 5?")
print(result.data.output)

Models​

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

model = aix.Model.get("openai/gpt-4o-mini/openai")
result = model.run(text="What is 2 + 2?")
print(result.data)

The execute endpoint takes an asset ID or a URL-encoded asset path. Inputs differ by model type; see Run a model and the sections after it.

Tools​

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

tool = aix.Tool.get("tavily/tavily-web-search/tavily")
result = tool.run(action="search", data={"query": "latest AI news"})
print(result.data)

A tool's actions and inputs differ per tool. List them with tool.actions, or copy snippets from the tool's card in the Marketplace.

Run a model​

POST https://models.aixplain.com/api/v2/execute/openai%2Fgpt-4o-mini%2Fopenai
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "text": "What is 2 + 2?"
}
{
    "status": "SUCCESS",
    "completed": true,
    "data": "2 + 2 equals 4.",
    "details": [{"index": 0, "message": {"role": "assistant", "content": "2 + 2 equals 4."}, "finish_reason": "stop"}],
    "runTime": 0.502,
    "usedCredits": 7.05e-06,
    "usage": {"prompt_tokens": 15, "completion_tokens": 8, "total_tokens": 23},
    "asset": {"assetId": "669a63646eb56306647e1091", "id": "openai/gpt-4o-mini/openai"}
}
FieldTypeDescription
datastringThe model's answer, or the polling URL for async jobs.
detailsarrayThe provider's message objects, with role, content and finish_reason.
usageobjectToken counts.
usedCreditsnumberCredits charged for the call.
runTimenumberServer-side run time in seconds.
assetobjectThe model that ran, by ID and path.

To also get the provider's unmodified response, add "options": {"includeRawData": true} to the body and read the top-level rawData field.

Set model parameters​

Pass parameters as top-level fields next to text:

POST https://models.aixplain.com/api/v2/execute/openai%2Fgpt-4o-mini%2Fopenai
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "text": "What are the colors of the rainbow?",
    "max_tokens": 20,
    "temperature": 0.8
}

Each model accepts its own parameters. Get them from the model's definition:

GET https://platform-api.aixplain.com/v2/models/669a63646eb56306647e1091
x-api-key: YOUR_API_KEY

The params array lists each parameter's name, required, dataType, availableOptions and defaultValues.

Stream LLM output​

Add "stream": true to get tokens as server-sent events. Each event is a data: line with an OpenAI-style chat.completion.chunk, and the stream ends with data: [DONE].

POST https://models.aixplain.com/api/v2/execute/openai%2Fgpt-4o-mini%2Fopenai
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "text": "Count to 3.",
    "stream": true
}
data: {"choices": [{"index": 0, "delta": {"role": "assistant", "content": ""}, "finish_reason": null}]}
data: {"choices": [{"index": 0, "delta": {"content": "1"}, "finish_reason": null}]}
...
data: {"choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}]}
data: {"choices": [], "usage": {"prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20}}
data: [DONE]

Read the text from choices[0].delta.content. The last event before [DONE] carries usage.

Send chat history and images​

For a conversation, pass a list of role and content messages as text. A message's content can also be a list of text and image_url parts for vision models such as GPT-4o Mini.

POST https://models.aixplain.com/api/v2/execute/openai%2Fgpt-4o-mini%2Fopenai
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "text": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What animal is in this image? One word."},
                {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"}}
            ]
        }
    ],
    "max_tokens": 10
}

The response's data is "Cat.". The provider downloads image URLs, so they must be public. To send an image you do not host, use a base64 data URI as the url, such as data:image/png;base64,iVBORw0KGgo....

Speech and video models​

Text-to-speech models take text and return a signed, time-limited URL to the audio in data:

POST https://models.aixplain.com/api/v2/execute/618ba6e4e2e1a9153ca2a3a2
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "text": "The quick brown fox jumps over the lazy dog."
}

Speech recognition models take an audio URL in source_audio and the spoken language. Pass the URL from the text-to-speech response to transcribe it:

POST https://models.aixplain.com/api/v2/execute/615dd18b6eb56373643b09d1
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "language": "en",
    "source_audio": "AUDIO_URL"
}
{
    "status": "SUCCESS",
    "completed": true,
    "data": "the quick brown fox jumps over the lazy dog",
    "confidence": 0.955996,
    "details": {"segments": [{"segment_id": 0, "start_time": 0.1, "end_time": 3.4, "text": "the quick brown fox jumps over the lazy dog", "confidence": 0.955996, "speaker": ""}]}
}

Video generation models, such as Seedance 1.5 pro (695ea397253de54a56dc5aa1), run asynchronously. Send the prompt in text, plus optional resolution, ratio and duration, then poll until data holds the video URL.

Upload a file​

The execute endpoint reads media from URLs. To send a local file, upload it to temporary storage, then pass the returned downloadUrl to the model.

  1. Request an upload URL:

    POST https://platform-api.aixplain.com/sdk/file/upload/temp-url
    x-api-key: YOUR_API_KEY
    Content-Type: application/x-www-form-urlencoded

    contentType=audio/wav&originalName=greeting.wav

    The response has name, key, uploadUrl, downloadUrl and headers.

  2. PUT the file to uploadUrl, with the same Content-Type you declared:

    curl -X PUT 'UPLOAD_URL' -H 'Content-Type: audio/wav' --data-binary @greeting.wav

  3. Pass downloadUrl to the model, for example as source_audio.

File typeUpload limit
Audio50 MB
Image25 MB
Documents (application/*)25 MB
Video300 MB
Database (.db, .sqlite, .sqlite3)300 MB
Other50 MB

A model can set tighter format or length limits; check its card in the Marketplace.

Run an agent​

Agent runs are always asynchronous. Send query as a top-level field:

POST https://platform-api.aixplain.com/v2/agents/{agent_id}/run
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "query": "What is 5 + 5?"
}
{
    "requestId": "1-bcb3388c-8df0-46f3-a48b-0807fdab96f9",
    "data": "https://platform-api.aixplain.com/sdk/agents/1-bcb3388c-8df0-46f3-a48b-0807fdab96f9/result"
}

Poll the URL in data until completed is true:

GET https://platform-api.aixplain.com/sdk/agents/{request_id}/result
x-api-key: YOUR_API_KEY
{
    "completed": true,
    "status": "SUCCESS",
    "data": {
        "input": "What is 5 + 5?",
        "output": "10",
        "steps": [...],
        "runTime": 1.86,
        "usedCredits": 0.001563,
        ...
    }
}

The answer is in data.output, and data.steps lists every model and tool call. Stop polling when status is SUCCESS or FAILED.

Multi-turn conversations​

To keep context across turns, create a session for the agent, then post each user message to it. This is the REST form of Sessions and memory.

POST https://platform-api.aixplain.com/v1/sessions
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "agentId": "YOUR_AGENT_ID",
    "name": "Support chat"
}

The response's id is the session ID. Post each message to the session:

POST https://platform-api.aixplain.com/v1/sessions/{session_id}/messages
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "role": "user",
    "content": "My name is Sam."
}

The response has a requestId. Poll https://platform-api.aixplain.com/sdk/agents/{request_id}/result for the answer, as in Run an agent. A later message such as "What is my name?" gets "Your name is Sam."

GET /v1/sessions/{session_id}/messages returns the transcript, and DELETE /v1/sessions/{session_id} deletes the session.

To keep the conversation on your side instead, send earlier turns in history on each run:

{
    "query": "What is my name?",
    "history": [
        {"role": "user", "content": "My name is Sam."},
        {"role": "assistant", "content": "Nice to meet you, Sam."}
    ]
}

Call an agent over MCP​

Every agent is also served as a hosted MCP server with a single tool. Connect from any MCP client that supports a remote server with a Bearer header.

POST https://models-mcp.aixplain.com/agent/mcp/{agent_id}
Authorization: Bearer YOUR_API_KEY
Accept: application/json, text/event-stream

x-api-key: YOUR_API_KEY also works in place of Authorization. Requests without the Accept header are rejected with 406.

warning

Use the 24-character agent ID in the URL. Path-style identifiers such as supplier/agent-name work for models and tools but not for agents.

tools/list returns one tool, named after the agent's path (for example aixplain/copywriter/aixplain), with these inputs:

InputRequiredPurpose
queryYesThe request for the agent.
sessionIdNoContinues a server-managed session. See Multi-turn conversations.
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "aixplain/copywriter/aixplain",
        "arguments": {"query": "Reply with exactly the single word: OK"}
    }
}

The server waits for the run to finish and returns:

{
    "content": [],
    "structuredContent": {
        "status": "SUCCESS",
        "data": "OK",
        "requestId": "ced03ab3-..."
    }
}

The agent's answer is in structuredContent.data, and content is empty. MCP clients that display only content may show an empty tool result.

Errors​

StatusCauseExample body
400Malformed body or missing field, such as query nested inside data{"message":["query should not be empty"],"error":"Bad Request","statusCode":400}
401Missing or invalid API key on a model call{"error":"Invalid api key. Please generate a new api key and try again."}
403Missing or invalid API key on an agent call{"message":"Forbidden resource","error":"Forbidden","statusCode":403}
492The input URL could not be downloaded{"error":"err.invalid_input_data_or_input_url"}

A model call can also return HTTP 201 with "status": "FAILED" when the provider rejects the input, and an async run can finish FAILED after it starts. Always check the final status, not only the HTTP code.

Next steps​