{"id":2101,"library":"llama-cloud","title":"Llama Cloud Python SDK","description":"The `llama-cloud` Python SDK is the official library for interacting with the Llama Cloud API, providing convenient access to services like LlamaParse for agentic OCR and document processing, structured data extraction, document classification, and RAG ingestion. The library offers both synchronous and asynchronous clients and is actively maintained with frequent releases, currently at version 2.3.0.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/run-llama/llama-cloud-py","tags":["llm","rag","api-client","document-processing","ocr","data-extraction","ai"],"install":[{"cmd":"pip install llama-cloud","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"LlamaCloud","correct":"from llama_cloud import LlamaCloud"},{"symbol":"AsyncLlamaCloud","correct":"from llama_cloud import AsyncLlamaCloud"},{"note":"While `import llama_cloud` works, importing `APIError` directly is cleaner for exception handling.","wrong":"import llama_cloud; try: ... except llama_cloud.APIError as e:","symbol":"APIError","correct":"from llama_cloud import APIError"}],"quickstart":{"code":"import os\nfrom llama_cloud import LlamaCloud\nfrom pathlib import Path\n\n# Ensure LLAMA_CLOUD_API_KEY is set in your environment variables\n# e.g., os.environ['LLAMA_CLOUD_API_KEY'] = 'llx-...' or using a .env file\nclient = LlamaCloud(\n    api_key=os.environ.get('LLAMA_CLOUD_API_KEY', '')\n)\n\n# Example: Upload a dummy file and create a parsing job\n# Replace with a real file path for actual usage\n# file_path = Path(\"path/to/your/document.pdf\")\n# with open(file_path, \"rb\") as f:\n#     file_obj = client.files.create(\n#         file=(file_path.name, f.read(), \"application/pdf\"),\n#         purpose=\"parse\",\n#     )\n\n# For demonstration, simulate a file_id to create a parsing job\n# In a real scenario, file_id would come from client.files.create() or an existing file.\ndummy_file_id = \"your-example-file-id\" # Replace with actual file_id if uploading\n\nif not dummy_file_id:\n    print(\"Please provide a valid file_id or upload a file first.\")\nelse:\n    try:\n        job = client.parsing.create(\n            tier=\"agentic\", # or \"fast\", \"cost_effective\"\n            version=\"latest\",\n            file_id=dummy_file_id,\n            # For example, to get markdown output:\n            output_options={\n                \"markdown\": {\n                    \"tables\": {\n                        \"output_tables_as_markdown\": True\n                    }\n                }\n            },\n            expand=[\"markdown\"]\n        )\n        print(f\"Created parsing job with ID: {job.id}\")\n        # You would typically poll the job status and retrieve results here\n        # For example, using client.parsing.get_job_result(job.id)\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n","lang":"python","description":"Initializes the Llama Cloud client using an API key from environment variables and demonstrates how to create a document parsing job. For actual usage, replace `dummy_file_id` with an ID obtained from uploading a file via `client.files.create()`."},"warnings":[{"fix":"Review the official Llama Cloud API documentation for updated `extraction` and `parse` endpoint usage and new metadata structures. Specifically, refer to the 'Migration Guide: Parse Upload Endpoint v1 to v2' for detailed changes.","message":"The v2.0.0 release introduced significant breaking changes, including the removal of the v1 extraction resource and a restructure of metadata. If you were using `extraction` features prior to v2.0.0, your code will need updates.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Migrate your codebase to use the `llama-cloud` package (version >=1.0) and update all imports and API calls accordingly. The new SDK provides improved performance and active development.","message":"The `llama-cloud-services` package is deprecated and will no longer be maintained after May 1, 2026. This older SDK has different import paths and API surface areas.","severity":"breaking","affected_versions":"<1.0.0 (of `llama-cloud-services`)"},{"fix":"Always store your `LLAMA_CLOUD_API_KEY` in environment variables or a secure key management service. The SDK automatically picks up `LLAMA_CLOUD_API_KEY` from environment variables, or it can be passed via the `api_key` parameter during client initialization using `os.environ.get('LLAMA_CLOUD_API_KEY')`.","message":"Hardcoding API keys directly in your application code is a security risk. API keys are user and project-scoped.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult the LlamaParse API v2 documentation for the correct use of `tier` and the new configuration objects when calling `client.parsing.create()` or `client.parsing.parse()`.","message":"LlamaParse API v2 introduced structured configuration objects (`input_options`, `output_options`, `processing_options`) instead of a flat list of parameters from v1. Old parameter names or structures from v1 will not work with v2 endpoints.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}