docs: improve API reference documentation with comprehensive client examples

This PR enhances the api.md documentation to provide more useful client reference information including:
- Quick start guide with immediate examples
- Detailed client initialization for both sync and async clients
- Comprehensive coverage of all high-level methods (run, stream, use, search)
- Complete documentation of core resources with code examples
- File handling patterns for input and output
- Error handling with full exception hierarchy
- Pagination examples (automatic and manual)
- Advanced features like raw response access and custom HTTP clients
- Async/await support with examples
- Common patterns for real-world usage
- Migration guide from v0.x to v1.0+

Fixes https://linear.app/replicate/issue/DP-660/generate-new-apimd-with-more-useful-client-reference

Author: zeke