OpenAI SDK Compatibility

Overview

The OpenAI Responses API is a stateful API designed for long-running tasks that require asynchronous processing. We’ve made our API compatible with the Responses API, allowing you to use the OpenAI SDK with Manus for complex reasoning tasks, document analysis, and multi-step workflows. Manus handles the heavy lifting while you track progress asynchronously, making it perfect for automation, research, and complex applications.

Prerequisites

Before you begin:

Sign up for a Manus account
Generate your API key from the dashboard
Install Python 3.10 or higher

Installation

Install the OpenAI Python SDK:

pip install openai==1.100.2

Note: We’ve tested compatibility with OpenAI Python SDK versions up to 1.100.2.

Manus uses API key-based authentication via headers. Set up your client with these approaches:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.manus.im",
    api_key="**",  # This can be any placeholder value
    default_headers={
        "API_KEY": "your-api-key"  # Your actual Manus API key
    },
)

The api_key parameter to the OpenAI client can be any placeholder value - Manus reads the actual API key from the API_KEY header.

Your First Task

When working with Manus, tasks run asynchronously, meaning they don’t block your program while they’re being processed. Before we dive into the code, let’s cover the different statuses a task can have:

running: The initial state when you first dispatch a task. It means the agent is actively working on your request.
pending: The agent has paused its work and is waiting for more input from a user. This often happens in interactive sessions.
completed: The task finished successfully, and the full results are now available to be retrieved.
error: The task could not be completed because it ran into an error.

Polling involves periodically checking the task’s status until it’s either completed or encounters an error. This approach is straightforward and works well for many use cases. If you’d like to see how to setup a webhook with Manus, check out our guide on how to do so.

Creating a Task

First, Let’s create a task using the Manus API. When you do this, you receive a response object that contains a unique id for your task. This id is crucial for tracking the task’s status.

from openai import OpenAI

client = OpenAI(
    base_url={BASE_URL},
    api_key="**",  # This can be any placeholder value
    default_headers={
        "API_KEY": {API_KEY}  # Your actual Manus API key
    },
)

# Create a simple task
response = client.responses.create(
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "What's the color of the sky?",
                },
            ],
        }
    ],
    extra_body={
        "task_mode": "agent",
        "agent_profile": "quality",
    },
)

print(f"Task created: {response.id}")
# Task created: a5ej4FnVPLP8Vjvb6FoeAu
print(f"Status: {response.status}")
# Status: running
print(f"Task URL: {response.metadata.get('task_url')}")
# Task URL: https://vida.butterfly-effect.dev/app/a5ej4FnVPLP8Vjvb6FoeAu

To find out about the status of your task, you can use the retrieve method to get the latest status of the task. This can be done with a simple while loop.

# When task is done, get the complete response
completed_response = client.responses.retrieve(response_id="m2rLPAbg5PW76A7GYWS72B")

while completed_response.status === "running":
    # Wait a few seconds before checking again to avoid spamming the API
    time.sleep(5) 
    
    print(f"Checking status for task {task_id}...")
    task_update = client.responses.retrieve(response_id=task_id)
    current_status = task_update.status
    print(f"Current status: {current_status}")

print("Task is no longer running.")
print(task_update)

Once the loop finishes, the task is completed, has failed or is pending your input. You can then inspect the final Response object to get the full conversation. The final result, including all messages from both the user and the assistant are contained in the output field.

Response(
    id='a5ej4FnVPLP8Vjvb6FoeAu',
    object='response',
    status='completed',
    model='manus-agent-quality',
    createdAt='1760348691',
    metadata={
        'credit_usage': '12', 
        'task_url': 'https://vida.butterfly-effect.dev/app/a5ej4FnVPLP8Vjvb6FoeAu'
    },
    output=[
        ResponseOutputMessage(
            id='jxdOzAoH8RxKi45YJvww2a',
            role='user',
            content=[
                ResponseOutputText(
                    text="What's the color of the sky?"
                )
            ]
        ),
        ResponseOutputMessage(
            id='lJLNeZP1bnHE0YsAPq3Vzd',
            role='assistant',
            content=[
                ResponseOutputText(
                    text='Understood, I will provide information about the color of the sky.'
                ),
                ResponseOutputText(
                    annotations=None,
                    text=None,
                    type='output_file',
                    logprobs=None,
                    fileUrl='<file url goes here>',
                    fileName='notion_benefits.md',
                    mimeType='text/markdown'
                )
            ]
        ),
        //...other conversation messages go here
    ]
)

The most important field here is output, which contains the full conversation history as a list of ResponseOutputMessage objects. Each message includes a role (user or assistant) and its content, allowing you to easily parse the entire interaction. You can see a full list of all of the output files and messages that Manus has generated in the output field of the Response object.

File Management

The Files API allows you to manage file uploads separately from task creation. This is useful when you want to reuse files across multiple tasks or pre-upload large files.

Uploading Files

To upload a file, first create a file record to get an upload URL, then upload your file to that URL:

import requests
from openai import BaseModel
from typing import Literal

class FileCreate(BaseModel):
    id: str
    object: Literal["file"]
    filename: str
    status: str
    upload_url: str
    upload_expires_at: str
    created_at: str

# Step 1: Create file record and get upload URL
file_record = client.post(
    "/files", 
    body={"filename": "berkshire_letter_2024.pdf"}, 
    cast_to=FileCreate
)

print(f"File ID: {file_record.id}")
# File ID: file-abc123xyz
print(f"Status: {file_record.status}")
# Status: pending
print(f"Upload URL: {file_record.upload_url}")

# Step 2: Download and upload the file
pdf_url = "https://www.berkshirehathaway.com/letters/2024ltr.pdf"
pdf_response = requests.get(pdf_url)

upload_response = requests.put(file_record.upload_url, data=pdf_response.content)
upload_response.raise_for_status()

print(f"File uploaded successfully: {file_record.id}")

The presigned upload URL expires in 3 minutes for security. Complete your upload before it expires.

Uploaded files are automatically deleted after 48 hours. Reference them in your tasks before they expire. If you’d like to delete them manually, you can do so using the Files API.

File Status

Files progress through the following states:

pending: File record created, waiting for upload to complete
uploaded: File successfully uploaded and ready to use in tasks
deleted: File has been deleted (manually or automatically after 48 hours)

Retrieving File Details

Check the status and details of your uploaded file:

# Get details for a specific file
file = client.files.retrieve(file_id="file-abc123xyz")

print(f"Filename: {file.filename}")
# Filename: berkshire_letter_2024.pdf
print(f"Status: {file.status}")
# Status: uploaded
print(f"Created: {file.created_at}")
# Created: 1760348691

Listing Files

Retrieve all files you’ve uploaded:

# Get all your files
files = client.files.list()

for file in files.data:
    print(f"{file.id}: {file.filename} - {file.status}")
# file-abc123xyz: berkshire_letter_2024.pdf - uploaded
# file-def456uvw: report.docx - uploaded

Deleting Files

Remove files you no longer need:

# Delete a specific file
client.files.delete(file_id="file-abc123xyz")
print("File deleted successfully")

Deleting a file marks it as deleted and you will no longer be able to use the file in tasks.

Working with Content

Text Input

For simple text-based tasks, use input_text:

response = client.responses.create(
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Explain quantum computing in simple terms.",
                },
            ],
        }
    ],
    extra_body={
        "task_mode": "agent",
        "agent_profile": "quality",
    },
)

Files

Include various file types in your tasks using these methods:

File ID
Public URL
Base64 Upload

# Best approach - use pre-uploaded files via Files API
response = client.responses.create(
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Summarize the key points from Warren Buffett's letter.",
                },
                {
                    "type": "input_file",
                    "file_id": "file-abc123xyz",  # Reference pre-uploaded file
                },
            ],
        },
    ],
    extra_body={"task_mode": "agent", "agent_profile": "quality"},
)

Supported file types:

Documents: PDF, DOCX, TXT, MD
Spreadsheets: CSV, XLSX
Code: JSON, YAML, Python, JavaScript, and more

When using base64, include the proper MIME type prefix (e.g., data:application/pdf;base64, for PDFs).

Images

Include images for visual analysis using these methods:

Public URL
Base64 Upload

# Use public image URLs directly
response = client.responses.create(
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "What's in this image?",
                },
                {
                    "type": "input_image",
                    "image_url": "https://example.com/image.jpg",
                },
            ],
        },
    ],
    extra_body={"task_mode": "agent", "agent_profile": "quality"},
)

Supported image formats:

PNG, JPEG/JPG, GIF, WebP

For images, use "type": "input_image" and provide the URL via image_url. Include proper MIME type prefixes for base64 uploads.

Multi-turn Conversations

Build sophisticated workflows by continuing conversations across multiple requests. Just use the previous_response_id or task_id to link to the previous conversation.

Context Preservation: The agent remembers previous context, uploaded files, and intermediate results across conversation turns, enabling complex multi-step tasks.

Using previous_response_id
Using task_id

# Initial request with image analysis
response = client.responses.create(
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What's in this image?"},
                {"type": "input_image", "image_url": "https://example.com/chart.png"},
            ],
        },
    ],
    extra_body={"task_mode": "agent", "agent_profile": "quality"},
)

response_id = response.id

# Continue the conversation
followup = client.responses.create(
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What does the data suggest about Q4 trends?"},
            ],
        },
    ],
    previous_response_id=response_id,  # Links to previous conversation
    extra_body={"task_mode": "agent", "agent_profile": "quality"},
)

Use either previous_response_id or task_id in extra_body, but not both in the same request.

Task Management

Retrieve all your tasks, including those created through the Manus webapp:

# Get all your tasks
response = client.get("/v1/tasks", cast_to=object)
tasks = response.data

for task in tasks:
    print(f"{task.id}: {task.status} - {task.metadata.get('task_title', 'Untitled')}")

This returns all your tasks, not just API-created ones.

Filtering and Search

Find specific tasks using these parameters:

By Status
By Search Query
By Date Range

# Filter by task status
response = client.get(
    "/v1/tasks?status=completed&status=running&limit=50",
    cast_to=object
)

Response format:

data: Array of task objects
first_id: ID of first task in results
last_id: ID of last task (for pagination)
has_more: Whether more tasks exist

Pagination

Handle large numbers of tasks efficiently:

from openai import BaseModel

class TaskList(BaseModel):
    data: list
    first_id: str
    last_id: str
    has_more: bool

all_tasks = []
after_cursor = None

while True:
    url = f"/v1/tasks?limit=50&order=desc"
    if after_cursor:
        url += f"&after={after_cursor}"

    response = client.get(url, cast_to=TaskList)
    all_tasks.extend(response.data)

    if not response.has_more:
        break

    after_cursor = response.last_id

print(f"Total tasks: {len(all_tasks)}")

Pagination Direction: order=desc moves from newest → oldest, order=asc moves from oldest → newest.

Available Parameters:

Parameter	Type	Description
`limit`	integer	Max tasks (1-1000, default: 100)
`after`	string	Pagination cursor
`order`	string	Sort direction: `"asc"` or `"desc"`
`order_by`	string	Sort field: `"created_at"` or `"updated_at"`
`query`	string	Search term
`status`	array	Filter by status
`created_after`	integer	Unix timestamp
`created_before`	integer	Unix timestamp

Deleting Tasks

Remove completed tasks to keep your workspace organized:

# Delete a specific task
client.responses.delete(response_id="task_id_here")

# Delete multiple tasks
task_ids = ["id1", "id2", "id3"]
for task_id in task_ids:
    client.responses.delete(response_id=task_id)

This permanently removes the task and all associated data. Save important outputs first!

Updating Tasks

Modify task settings after creation:

# Update task properties
client.put(
    "/v1/tasks/task_id_here",
    options={
        "extra_headers": {"API_KEY": "your-api-key"},
        "extra_body": {
            "enable_shared": True,  # Enable public sharing
            "enable_visible_in_task_list": False,  # Hide from list
            "title": "Updated Title"  # Rename task
        },
    },
)

Useful for:

Enabling sharing after task completion
Hiding/showing tasks in your workspace
Renaming tasks for better organization

Update only the fields you want to change - others remain unchanged.

Make tasks accessible to others using shareable links:

# Create task with public sharing
response = client.responses.create(
    input=[{"role": "user", "content": [{"type": "input_text", "text": "Research report"}]}],
    extra_body={
        "task_mode": "agent",
        "agent_profile": "quality",
        "create_shareable_link": True,  # Enable public access
    },
)

# Access the shareable URL
share_url = response.metadata.get('share_url')
task_url = response.metadata.get('task_url')  # Your private URL

print(f"Share with others: {share_url}")
print(f"Your private access: {task_url}")

Anyone with the share URL can view the task and its results. Only enable for non-sensitive content.

Task Visibility

Control which tasks appear in your workspace:

# Hide tasks from your task list (useful for automation)
response = client.responses.create(
    input=[{"role": "user", "content": [{"type": "input_text", "text": "Automated process"}]}],
    extra_body={
        "task_mode": "agent",
        "agent_profile": "quality",
        "hide_in_task_list": True,  # Won't appear in your workspace
    },
)

# Still accessible via direct URL
print(f"Hidden task URL: {response.metadata.get('task_url')}")

Best Practices

Workspace Management:

Delete completed tasks you no longer need
Use hide_in_task_list for automated workflows to avoid clutter
Save important outputs before deleting tasks

Security:

Only enable create_shareable_link for non-sensitive tasks
Be mindful of what information you’re sharing publicly
Use environment variables for API keys in production

Performance:

Use appropriate agent profiles (speed for quick tasks, quality for complex analysis)
Monitor task status rather than polling constantly
Batch similar tasks when possible for efficiency

Error Handling:

Always check task status before accessing results
Handle failed tasks gracefully in your applications
Save task IDs for debugging and monitoring

Getting Started

Webhooks

Tasks

Files

Webhooks API

SDK

Connectors

Integrations

OpenAI SDK Compatibility

Overview

Prerequisites

Installation

Your First Task

Creating a Task

File Management

Uploading Files

File Status

Retrieving File Details

Listing Files

Deleting Files

Working with Content

Text Input

Files

Images

Multi-turn Conversations

Task Management

Filtering and Search

Deleting Tasks

Updating Tasks

Task Visibility

Best Practices

Getting Started

Webhooks

Tasks

Files

Webhooks API

SDK

Connectors

Integrations

​Overview

​Prerequisites

​Installation

​Your First Task

​Creating a Task

​File Management

​Uploading Files

​File Status

​Retrieving File Details

​Listing Files

​Deleting Files

​Working with Content

​Text Input

​Files

​Images

​Multi-turn Conversations

​Task Management

​Filtering and Search

​Pagination

​Deleting Tasks

​Updating Tasks

​Sharing & Visibility

​Public Sharing

​Task Visibility

​Best Practices

Overview

Prerequisites

Installation

Your First Task

Creating a Task

File Management

Uploading Files

File Status

Retrieving File Details

Listing Files

Deleting Files

Working with Content

Text Input

Files

Images

Multi-turn Conversations

Task Management

Filtering and Search

Pagination

Deleting Tasks

Updating Tasks

Sharing & Visibility

Public Sharing

Task Visibility

Best Practices