Adds support for the legacy api_token parameter in both Replicate and
AsyncReplicate client initialization as an alternative to bearer_token.
This enables backward compatibility with v1.x client code that uses:
- Client(api_token="...")
- AsyncClient(api_token="...")
The implementation:
- Accepts both api_token and bearer_token parameters
- Raises clear error if both are provided
- Maps api_token to bearer_token internally
- Maintains existing environment variable behavior
- Includes comprehensive test coverage

...xamples
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 

Update all documentation examples to use 'replicate' as the variable name
instead of 'client' for better consistency with the library name and
improved readability.

- Reorder high-level methods to show use() first as the recommended approach
- Add "(Recommended)" label to use() method
- Expand use() examples with more detailed usage patterns
- Update Quick Start to demonstrate use() as the primary pattern
- Clarify that use() creates Pythonic callable functions
- Keep run() as secondary option for one-off predictions

...o-banana
Replace all model references in examples:
- stability-ai/sdxl → google/nano-banana
- meta/llama-2-70b-chat → anthropic/claude-4-sonnet
- black-forest-labs/flux-schnell → google/nano-banana
- stability-ai/stable-diffusion → google/nano-banana
This provides more whimsical and memorable example model names while
maintaining the same API patterns and functionality demonstrations.

- Remove explicit `replicate = Replicate()` from most examples
- Use `import replicate` pattern which automatically uses REPLICATE_API_TOKEN
- Keep one comprehensive example showing custom client configuration with environment variables
- Maintain explicit client instantiation only where showing advanced configuration
- Update Quick Start, Type Hints, and Migration Guide sections accordingly
This makes the examples cleaner and follows the most common usage pattern
where users rely on the default environment variable configuration.

...ut types
Based on actual model schemas:
- google/nano-banana: only requires 'prompt', returns image URL
- anthropic/claude-4-sonnet: only requires 'prompt', returns text string
Changes:
- Simplified all examples to use only the required 'prompt' input
- Updated variable names to clarify output types (image_url vs text)
- Added comments showing what each model returns
- Removed unnecessary optional parameters from examples
- Updated async and streaming examples to show correct output types
- Fixed batch processing example to be more specific about images

Changed all section headings throughout the API documentation to follow
sentence case convention (only capitalizing the first word) for better
consistency and modern documentation style.