Integration Guidelines
This guide provides essential information for integrating with the our API, including endpoint selection, polling best practices, and proper handling of generated content.
API Endpoints Overview
Primary Global Endpoint
api.bfl.ai
- Primary Endpoint
- Routes requests across all available clusters globally
- Provides automatic failover between clusters for enhanced uptime
- Intelligent load distribution prevents bottlenecks during high traffic periods
- Important: Always use the
polling_url
returned in responses when using this endpoint - Suitable for: Standard inference
- Not suitable for: Finetuning operations and finetuned model inference workloads (finetuning remains region-specific)
Regional Endpoints
api.eu.bfl.ai
- European Multi-cluster Endpoint
- Multi-cluster routing limited to EU regions
- GDPR compliant
- Provides the same uptime and load balancing benefits within EU regions
api.us.bfl.ai
- US Multi-cluster Endpoint
- Multi-cluster routing limited to US regions
- Provides the same uptime and load balancing benefits within US regions
Legacy Regional Endpoints
api.eu1.bfl.ai
- EU Single-cluster Endpoint
- Required for finetuning operations in EU region
- Single cluster, no automatic failover
api.us1.bfl.ai
- US Single-cluster Endpoint
- Required for finetuning operations in US region
- Single cluster, no automatic failover
Key Benefits of New Endpoints
Enhanced Reliability
Reduced downtime through automatic cluster failover
Better Performance
Intelligent traffic distribution prevents overload during peak usage
Seamless Experience
Load balancing happens transparently on our end
Polling URL Usage
When using the primary global endpoint (api.bfl.ai
) or regional endpoints (api.eu.bfl.ai
, api.us.bfl.ai
), you must use the polling_url
returned in the initial request response.
Webhook Users: If you’re using webhooks to receive results, no changes are needed. The polling_url
requirement only applies when implementing async polling behavior to check request status.
Example Implementation
Content Delivery and Storage Guidelines
Delivery URLs
Generated images are served from region-specific delivery URLs:
- EU:
delivery-eu1.bfl.ai
- US:
delivery-us1.bfl.ai
Important Delivery Considerations
Not for Direct Serving: The result.sample
URLs from delivery endpoints are not meant to be served directly to end users.
No CORS Support: We do not enable CORS on delivery URLs, which means they cannot be used directly in web browsers for cross-origin requests.
10-Minute Expiration: Generated images expire after 10 minutes and become inaccessible.
Network Access: If your infrastructure uses firewalls or network restrictions, ensure you whitelist the delivery endpoints (delivery-eu1.bfl.ai
, delivery-us1.bfl.ai
) to allow downloading generated images.
Recommended Image Handling
Download and Re-serve Pattern:
Migration Checklist
Update API Endpoints
- Replace legacy endpoints with appropriate new endpoints based on your needs
- Use
api.bfl.ai
for global load balancing - Use
api.eu.bfl.ai
orapi.us.bfl.ai
for regional preferences
Implement Polling URL Handling
- Ensure your code extracts and uses the
polling_url
from API responses - Update polling logic to use the provided polling URL instead of hardcoded endpoints
Update Finetuning Workflows
- Continue using region-specific endpoints (
api.eu1.bfl.ai
,api.us1.bfl.ai
) for finetuning - Ensure finetuned model inference uses the same region as training
Implement Proper Image Handling
- Set up download and re-serve infrastructure for generated images
- Plan for 10-minute expiration window
- Consider implementing CDN or cloud storage for better performance
Best Practices
Error Handling
Rate Limiting
- Maximum 24 concurrent requests for most endpoints
- Maximum 6 concurrent requests for
flux-kontext-max
- Implement exponential backoff for 429 responses
Content Management
- Download images immediately upon generation completion
- Implement proper error handling for expired URLs
- Consider implementing a queue system for high-volume applications
- Use appropriate storage solutions (CDN, cloud storage) for serving images to users