Pinata IPFS Client

A Python client for interacting with Pinata's IPFS API to upload files and generate signed URLs.

Installation

pip install -r requirements.txt

Usage

Initialize the Client

from pinata import Pinata

# Initialize with your Pinata Bearer token
pinata = Pinata(bearer_token="your_bearer_token_here")

Upload Files

Upload a file to IPFS through Pinata:

# Open your file
with open('path/to/your/file.jpg', 'rb') as file:
    # Upload file and get CID
    cid = pinata.upload_files(
        uploaded_file=file,
        filename="file.jpg",
        mime="image/jpeg"  # Optional: will be auto-detected if not provided
    )

if cid:
    print(f"File uploaded successfully! CID: {cid}")
else:
    print("Upload failed")

Generate Signed URLs

Generate a signed URL for accessing your uploaded file:

# Generate signed URL
signed_url = pinata.retrieve_file_url(
    gateway_url="https://your-gateway.pinata.cloud/",
    cid="your_file_cid_here",
    method="GET",  # Optional: defaults to GET
    expires=31536000  # Optional: defaults to 1 year in seconds
)

if signed_url:
    print(f"Signed URL: {signed_url}")
else:
    print("Failed to generate signed URL")

Features

• Automatic MIME type detection for files
• Comprehensive error handling
• Debug logging for troubleshooting
• Support for custom gateway URLs
• Configurable URL expiration times

Error Handling

The client includes built-in error handling and will:

• Print detailed error messages for debugging
• Return None if an operation fails
• Print response content for failed API requests

API Parameters

upload_files()

• uploaded_file: File object (opened in binary mode)
• filename: String name of the file
• mime: Optional MIME type (auto-detected if not provided)

retrieve_file_url()

• gateway_url: Your Pinata gateway URL
• cid: Content ID of the uploaded file
• method: HTTP method for the signed URL (default: "GET")
• expires: URL expiration time in seconds (default: 31536000 / 1 year)

Requirements

• Python 3.6+
• requests library
• Active Pinata account with API access
• Valid Pinata Bearer token

Error Messages

Common error messages you might encounter:

• "Error uploading file": Indicates an issue with the file upload request
• "A general error occurred": Indicates an unexpected error during execution
• Response content will be printed for debugging purposes

Security Notes

• Never commit your bearer token to version control
• Consider using environment variables for sensitive credentials
• Monitor URL expiration times based on your security requirements

Contributing

Feel free to submit issues and enhancement requests!