docs: improve API reference documentation with comprehensive client examples #71
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR enhances the api.md documentation to provide more useful client reference information.
Summary
Testing locally
To review the improved documentation:
Linear Issue
https://linear.app/replicate/issue/DP-660/generate-new-apimd-with-more-useful-client-reference
Prompts