Python SDK

The MagicalAPI Python SDK provides seamless access to our services through a fully type-annotated and asynchronous client.

Requirements

• Python 3.8 or higher
• An API key

Installation

uv

uv pip install magicalapi

pip

pip install magicalapi

Poetry

poetry add magicalapi

Pipenv

pipenv install magicalapi

Getting Started

Client Configuration

You can initialize the client in two ways:

Using .env file (Recommended)

.env

MAG_API_KEY="mag_1234567"

app.py

from magicalapi.client import AsyncClient

client = AsyncClient()  # API key loaded from .env

Direct initialization

from magicalapi.client import AsyncClient

API_KEY = "mag_123456"
client = AsyncClient(api_key=API_KEY)

Environment Variables

All settings use the MAG_ prefix and are case-insensitive:

• MAG_EXAMPLE
• Mag_example
• mag_EXAMPLE

Usage Examples

Resume Parser Service

import asyncio
from magicalapi.client import AsyncClient
from magicalapi.errors import APIServerError, APIServerTimedout
from magicalapi.types.base import ErrorResponse

resume_url = (
    "https://resume-resource.com/wp-content/uploads/00123-sales-professional-resume.pdf"
)
output_file_name = "resume_parser.json"

async def main():
    try:
        async with AsyncClient() as client:
            response = await client.resume_parser.get_resume_parser(url=resume_url)

            if isinstance(response, ErrorResponse):
                print("Error:", response.message)
            else:
                print("Credits used:", response.usage.credits)
                
                # Save response to a JSON file
                with open(output_file_name, "w") as file:
                    file.write(response.model_dump_json(indent=3))
                    print(f"Response saved to {output_file_name}")

    except (APIServerError, APIServerTimedout) as e:
        print("Server error:", e)
    except Exception as e:
        print("An error occurred:", str(e))

if __name__ == "__main__":
    asyncio.run(main())

Error Handling

As shown in the example below, this SDK provides predefined Exceptions that you can import and handle using Python's try/except blocks:

from magicalapi.errors import APIServerError, APIServerTimedout

try:
    # Your API call here
    pass
except APIServerError:
    print("A server error occurred.")
except APIServerTimedout:
    print("The request timed out.")
except Exception as e:
    print("An unexpected error occurred:", str(e))

Additional Resources

• Examples Directory - More code examples
• API Reference - Complete API documentation
• Services Documentation - Available API services

note

Need help? Check out our Support page or request a feature.