# AI/ML API — how to use (mcp.ai)

Connect your AI/ML API account and use 30 tools for artificial intelligence straight from your AI agent. Connect with your own API key. AI/ML API provides a suite of AI models and solutions for various tasks, including text generation, image processing, and more.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_ai_ml_api?ms=1787293440000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `ai_ml_api_cancel_run`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/ai_ml_api`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/ai_ml_api/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/ai_ml_api/cancel/run` — Tool to cancel a run that is currently in progress. Use when you need to stop an assistant run before it completes.
  - body: { run_id: string, thread_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/create/assistant` — Tool to create an AI assistant with configurable model, instructions, and tools. Use when you need to set up a new assistant that can maintain conversation context and use tools like code_interpreter 
  - body: { name?: string, model: string, tools?: object[], top_p?: number, metadata?: object, description?: string, temperature?: number, instructions?: string, tool_resources?: object, response_format?: object|string, reasoning_effort?: string }
- `POST https://api.mcp.ai/api/ai_ml_api/create/message` — Tool to create a new message in a thread. Use when you need to add a user or assistant message to an existing conversation thread.
  - body: { role: string, content: string|object[], metadata?: object, thread_id: string, attachments?: object[] }
- `POST https://api.mcp.ai/api/ai_ml_api/create/run` — Tool to create a run that executes an assistant on a thread. The assistant processes messages in the thread and generates responses based on its instructions and available tools.
  - body: { model?: string, tools?: object[], top_p?: number, metadata?: object, thread_id: string, temperature?: number, tool_choice?: string|object, assistant_id: string, instructions?: string, response_format?: string|object, max_prompt_tokens?: integer, additional_messages?: object[], parallel_tool_calls?: boolean, truncation_strategy?: object, max_completion_tokens?: integer }
- `POST https://api.mcp.ai/api/ai_ml_api/create/thread` — Tool to create a new thread for conversation with an assistant. Threads store messages and maintain context across interactions. Use when starting a new conversation or when you need a fresh context f
  - body: { messages?: object[], metadata?: object, tool_resources?: object }
- `POST https://api.mcp.ai/api/ai_ml_api/delete/assistant` — Tool to delete an assistant by ID. Use when you need to remove an assistant that is no longer needed.
  - body: { assistant_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/delete/message` — Tool to delete a specific message from a thread. Use when you need to remove an unwanted or erroneous message from a conversation thread.
  - body: { thread_id: string, message_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/delete/thread` — Tool to delete a thread by its ID. Use when you need to remove an existing thread from the system.
  - body: { thread_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/get/assistant` — Tool to retrieve details of a specific assistant by ID. Use when you need to fetch configuration, model settings, instructions, or available tools for an existing assistant.
  - body: { assistant_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/get/billing/balance` — Tool to retrieve the current billing balance for the account. Use when you need to check available credits, balance status, or auto-debit configuration.
- `POST https://api.mcp.ai/api/ai_ml_api/get/luma/generation` — Tool to fetch Luma AI video generation results by generation IDs. Use after creating a generation to check its status and retrieve the generated video URL when completed.
  - body: { ids: string }
- `POST https://api.mcp.ai/api/ai_ml_api/get/message` — Tool to retrieve information about a specific message by its ID. Use when you need to fetch details of a particular message in a thread.
  - body: { thread_id: string, message_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/get/response` — Tool to retrieve a previously generated model response by its unique ID. Use when you need to access details of a specific response, including its output, status, and usage statistics.
  - body: { include?: string[], response_id: string, starting_after?: integer, include_obfuscation?: boolean }
- `POST https://api.mcp.ai/api/ai_ml_api/get/run` — Tool to retrieve a specific run by ID from a thread. Use when you need to check the status, results, or details of a previously created run.
  - body: { run_id: string, thread_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/get/run/step` — Tool to retrieve a specific run step by its ID within a thread and run. Use when you need detailed information about a particular step's execution status and results.
  - body: { run_id: string, step_id: string, thread_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/get/thread` — Tool to retrieve information about a specific thread by ID. Use when you need to fetch thread details, metadata, or available tool resources for an existing conversation thread.
  - body: { thread_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/list/assistants` — Tool to list all assistants associated with the account. Use when you need to retrieve available assistants with pagination support.
  - body: { after?: string, limit?: integer, order?: string, before?: string }
- `POST https://api.mcp.ai/api/ai_ml_api/list/batches` — Tool to get the status or results of a batch processing job. Use when you need to check the progress or retrieve results of a previously submitted batch.
  - body: { batch_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/list/luma/generations` — Tool to fetch user's Luma AI video generations. Use when you need to retrieve a list of all Luma AI video generation tasks for the authenticated user.
  - body: { limit?: integer, offset?: integer }
- `POST https://api.mcp.ai/api/ai_ml_api/list/messages` — Tool to retrieve a list of messages from a specific thread. Use when you need to fetch conversation history or message content from an AI assistant thread.
  - body: { after?: string, limit?: integer, order?: string, before?: string, run_id?: string, thread_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/list/models` — Tool to list all available AI models from the AI/ML API. Use when you need to retrieve the complete catalog of 400+ models including chat, image, video, voice, and other model types.
- `POST https://api.mcp.ai/api/ai_ml_api/list/models/with/details` — Tool to list all available AI/ML models with detailed information including pricing, features, and capabilities. Use when you need to discover available models or get comprehensive model metadata.
- `POST https://api.mcp.ai/api/ai_ml_api/list/run/steps` — Tool to list the steps in a run. Use when you need to retrieve and examine the execution steps of a specific run within a thread.
  - body: { after?: string, limit?: integer, order?: string, before?: string, run_id: string, thread_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/list/runs` — Tool to list all runs for a specific thread. Use when you need to retrieve runs with pagination support.
  - body: { after?: string, limit?: integer, order?: string, before?: string, thread_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/submit/tool/outputs` — Tool to submit tool outputs for a run that requires action. Use when a run has status 'requires_action' and needs tool call results to continue execution.
  - body: { run_id: string, stream?: boolean, thread_id: string, tool_outputs: object[] }
- `POST https://api.mcp.ai/api/ai_ml_api/text/chat/completion` — Tool to generate text completions or chat responses using a specified LLM model. Use after assembling the conversation history to produce the next response.
  - body: { n?: integer, stop?: string[], user?: string, model: string, top_p?: number, stream?: boolean, messages: object[], logit_bias?: object, max_tokens?: integer, temperature?: number, presence_penalty?: number, frequency_penalty?: number }
- `POST https://api.mcp.ai/api/ai_ml_api/update/assistant` — Tool to modify an existing assistant's properties including name, instructions, model, and tools. Use when you need to update an assistant's configuration or behavior after it has been created.
  - body: { name?: string, model?: string, tools?: object[], top_p?: number, metadata?: object, description?: string, temperature?: number, assistant_id: string, instructions?: string, tool_resources?: object, response_format?: object, reasoning_effort?: string }
- `POST https://api.mcp.ai/api/ai_ml_api/update/message` — Tool to modify metadata for a specific message in a thread. Use when you need to update message metadata such as tags or custom fields.
  - body: { metadata?: object, thread_id: string, message_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/update/run` — Tool to update a run's metadata with key-value pairs. Use when you need to attach or modify additional information for a specific run.
  - body: { run_id: string, metadata?: object, thread_id: string }
- `POST https://api.mcp.ai/api/ai_ml_api/update/thread` — Tool to update thread metadata and tool resources in the AI/ML API. Use when you need to modify existing thread properties or attach resources.
  - body: { metadata?: object, thread_id: string, tool_resources?: object }

## Example prompts
- "What can I do in AI/ML API?"
- "Show me a summary of my AI/ML API account"

## More
- Page: https://mcp.ai/ai_ml_api
- Agent spec (llms.txt): https://mcp.ai/ai_ml_api/llms.txt
- Postman collection: https://mcp.ai/ai_ml_api/postman.json