Download the PHP package lanos/php-bfl without Composer

PHP Black Forest Labs SDK

A professional PHP SDK for Black Forest Labs' FLUX API, providing easy integration for AI-powered image generation and fine-tuning services.

Features

• Complete API Coverage: All FLUX API endpoints including image generation, fine-tuning, and utilities
• Type-Safe: Full PHP 8.1+ type hints and strict types for better IDE support and error detection
• Fluent API: Intuitive builder pattern for constructing complex requests
• Error Handling: Comprehensive exception handling with detailed error messages
• Async Support: Built-in polling mechanisms for handling async image generation tasks
• PSR Standards: Follows PSR-4 autoloading and PSR-12 coding standards
• Well Documented: Extensive inline documentation and examples

Installation

Install via Composer:

Quick Start

API Key Setup

1. Sign up at Black Forest Labs
2. Get your API key from the dashboard
3. Set it as an environment variable or pass it directly to the client:

Core Services

The SDK is organized into three main services:

Image Generation Service

Generate images using various FLUX models:

Advanced Image Operations

Fine-tuning Service

Train custom models and use them for generation:

Utility Service

Handle task polling and result retrieval:

Request Builder

Use the fluent builder pattern for complex requests:

Error Handling

The SDK provides comprehensive error handling:

Response Objects

All responses are returned as typed objects:

Configuration Options

Customize the HTTP client:

Best Practices

1. Always Handle Async Operations

2. Use Appropriate Safety Tolerance

3. Optimize Image Dimensions

4. Handle Rate Limits

Examples

See the examples/ directory for complete working examples:

• examples/basic_generation.php - Basic image generation
• examples/advanced_generation.php - Advanced features
• examples/fine_tuning.php - Fine-tuning workflow
• examples/image_editing.php - Fill, expand, and control
• examples/polling_patterns.php - Different polling strategies

Complete API Reference

This section provides comprehensive documentation for all available SDK methods and endpoints.

FluxClient

The main client class providing access to all services.

Constructor

Parameters:

• $apiKey (string) - Your Black Forest Labs API key
• $options (array) - Optional Guzzle HTTP client configuration

Service Access Methods

• imageGeneration() - Access image generation services
• finetune() - Access fine-tuning services
• utility() - Access utility services

ImageGeneration Service

Access via $client->imageGeneration(). Handles all image generation operations.

Core Generation Methods

flux1Pro(Flux1ProRequest $request): ImageGenerationResponse

Generate images with FLUX1 Pro model - highest quality, balanced performance.

Endpoint: POST /flux-pro

Parameters: Use ImageRequestBuilder to construct the request object.

Example:

flux1Dev(array $params): ImageGenerationResponse

Generate images with FLUX1 Dev model - development model, faster generation.

Endpoint: POST /flux-dev

Parameters:

• prompt (string) - Text description of desired image
• width (int, optional) - Image width (default: 1024)
• height (int, optional) - Image height (default: 768)
• steps (int, optional) - Denoising steps (default: 28)
• guidance (float, optional) - Guidance scale (default: 2.5)
• seed (int, optional) - Seed for reproducible results

Example:

flux11Pro(array $params): ImageGenerationResponse

Generate images with FLUX 1.1 Pro model - improved quality and performance.

Endpoint: POST /flux-pro-1.1

Parameters:

• prompt (string) - Text description
• width (int, optional) - Image width
• height (int, optional) - Image height
• steps (int, optional) - Denoising steps
• guidance (float, optional) - Guidance scale
• seed (int, optional) - Seed value

flux11ProUltra(array $params): ImageGenerationResponse

Generate images with FLUX 1.1 Pro Ultra model - highest quality available.

Endpoint: POST /flux-pro-1.1-ultra

Parameters:

• prompt (string) - Text description
• aspect_ratio (string, optional) - Aspect ratio (e.g., '1:1', '16:9')
• raw (bool, optional) - Output raw format
• safety_tolerance (int, optional) - Safety filtering level (0-6)

Example:

Contextual Generation Methods

fluxKontextPro(array $params): ImageGenerationResponse

Edit or create images with Flux Kontext Pro.

Endpoint: POST /flux-kontext-pro

fluxKontextMax(array $params): ImageGenerationResponse

Edit or create images with Flux Kontext Max.

Endpoint: POST /flux-kontext-max

Image Editing Methods

flux1Fill(array $params): ImageGenerationResponse

Fill/inpaint specific areas of an image using FLUX1 Fill Pro.

Endpoint: POST /flux-pro-1.0-fill

Required Parameters:

• image (string) - Base64 encoded input image
• prompt (string) - Description for the fill area

Optional Parameters:

• mask (string) - Base64 encoded mask image
• width (int) - Output width
• height (int) - Output height

Example:

flux1Expand(array $params): ImageGenerationResponse

Expand an image by adding pixels on any side.

Endpoint: POST /flux-pro-1.0-expand

Required Parameters:

• image (string) - Base64 encoded input image

Optional Parameters:

• top (int) - Pixels to add on top
• bottom (int) - Pixels to add on bottom
• left (int) - Pixels to add on left
• right (int) - Pixels to add on right
• prompt (string) - Description for expanded areas

Example:

Control Methods

flux1Canny(array $params): ImageGenerationResponse

Generate images using Canny edge detection as control guidance.

Endpoint: POST /flux-pro-1.0-canny

Required Parameters:

• prompt (string) - Text description
• control_image (string) - Base64 encoded control image

Optional Parameters:

• canny_low_threshold (int) - Low threshold for edge detection (default: 50)
• canny_high_threshold (int) - High threshold for edge detection (default: 200)

Example:

flux1Depth(array $params): ImageGenerationResponse

Generate images using depth information as control guidance.

Endpoint: POST /flux-pro-1.0-depth

Required Parameters:

• prompt (string) - Text description
• control_image (string) - Base64 encoded depth control image

Finetune Service

Access via $client->finetune(). Handles fine-tuning operations and fine-tuned model usage.

Management Methods

create(array $params): array

Create a new fine-tuned model from training images.

Endpoint: POST /finetune

Required Parameters:

• file_data (string) - Base64 encoded training data ZIP file
• finetune_comment (string) - Description of the fine-tune
• mode (string) - Training mode ('style', 'object', etc.)
• trigger_word (string) - Trigger word for the model
• iterations (int) - Number of training iterations

Example:

listMyFinetunes(): array

List all fine-tunes belonging to the authenticated user.

Endpoint: GET /my_finetunes

Returns: Array containing finetunes list

Example:

getDetails(string $finetuneId): array

Get detailed information about a specific fine-tune.

Endpoint: GET /finetune_details

Parameters:

• finetune_id (string) - ID of the fine-tune

delete(string $finetuneId): array

Delete a previously created fine-tune.

Endpoint: POST /delete_finetune

Parameters:

• finetune_id (string) - ID of the fine-tune to delete

Generation Methods with Fine-tuned Models

generateWithFinetunedPro(array $params): ImageGenerationResponse

Generate images using a fine-tuned FLUX Pro model.

Endpoint: POST /flux-pro-finetuned

Required Parameters:

• finetune_id (string) - ID of the fine-tuned model
• prompt (string) - Text description (should include trigger word)

Optional Parameters:

• finetune_strength (float) - Strength of fine-tuning effect (default: 1.0)
• width, height, steps, guidance, etc. - Standard generation parameters

Example:

generateWithFinetunedUltra(array $params): ImageGenerationResponse

Generate images using a fine-tuned FLUX 1.1 Pro Ultra model.

Endpoint: POST /flux-pro-1.1-ultra-finetune

Required Parameters:

• finetune_id (string) - ID of the fine-tuned model
• prompt (string) - Text description

generateWithFinetunedDepth(array $params): ImageGenerationResponse

Generate images using fine-tuned FLUX1 Depth Pro with control guidance.

Endpoint: POST /flux-pro-1.0-depth-finetune

Required Parameters:

• finetune_id (string) - ID of the fine-tuned model
• prompt (string) - Text description
• control_image (string) - Base64 encoded depth control image

generateWithFinetunedCanny(array $params): ImageGenerationResponse

Generate images using fine-tuned FLUX1 Canny Pro with edge control.

Endpoint: POST /flux-pro-1.0-canny-finetune

Required Parameters:

• finetune_id (string) - ID of the fine-tuned model
• prompt (string) - Text description
• control_image (string) - Base64 encoded edge control image

generateWithFinetunedFill(array $params): ImageGenerationResponse

Generate images using fine-tuned FLUX1 Fill Pro for inpainting.

Endpoint: POST /flux-pro-1.0-fill-finetune

Required Parameters:

• finetune_id (string) - ID of the fine-tuned model
• image (string) - Base64 encoded input image

Optional Parameters:

• mask (string) - Base64 encoded mask image

Utility Service

Access via $client->utility(). Handles task status checking and result polling.

getResult(string $taskId): GetResultResponse

Retrieve the current status or final result for a task.

Endpoint: GET /get_result

Parameters:

• id (string) - Task identifier from generation request

Returns: GetResultResponse object

Example:

pollResult(string $taskId, int $maxAttempts = 60, int $delaySeconds = 5): GetResultResponse

Poll for task completion with automatic retries.

Parameters:

• taskId (string) - Task identifier
• maxAttempts (int) - Maximum polling attempts (default: 60)
• delaySeconds (int) - Delay between attempts in seconds (default: 5)

Example:

waitForCompletion(string $taskId): GetResultResponse

Wait for task completion with sensible defaults (120 attempts, 3 second delay).

Parameters:

• taskId (string) - Task identifier

Example:

isTaskComplete(string $taskId): bool

Check if a task is complete without polling.

Returns: Boolean indicating completion status

getProgress(string $taskId): ?float

Get task progress percentage if available.

Returns: Progress as float (0.0-100.0) or null if not available

ImageRequestBuilder

Fluent builder for constructing complex image generation requests.

Factory Method

create(): ImageRequestBuilder

Create a new builder instance.

Example:

Configuration Methods

withPrompt(string $prompt): ImageRequestBuilder

Set the text prompt for image generation.

withImagePrompt(string $imagePrompt): ImageRequestBuilder

Set an optional image prompt (base64 encoded).

withDimensions(int $width, int $height): ImageRequestBuilder

Set exact pixel dimensions for the output image.

Example:

withAspectRatio(string $ratio, int $baseSize = 1024): ImageRequestBuilder

Set dimensions using aspect ratio with automatic calculation.

Parameters:

• ratio (string) - Aspect ratio like '16:9', '4:3', '1:1'
• baseSize (int) - Base dimension for calculation (default: 1024)

Example:

withSteps(int $steps): ImageRequestBuilder

Set the number of denoising steps (more steps = higher quality, slower).

withPromptUpsampling(bool $enabled = true): ImageRequestBuilder

Enable or disable prompt upsampling for enhanced prompt processing.

withSeed(int $seed): ImageRequestBuilder

Set a specific seed for reproducible results.

withRandomSeed(): ImageRequestBuilder

Generate and set a random seed for varied results.

withGuidance(float $guidance): ImageRequestBuilder

Set classifier guidance scale (how closely to follow the prompt).

Typical values: 1.0-10.0 (default: 2.5)

withInterval(float $interval): ImageRequestBuilder

Set interval for progressive updates.

withSafetyTolerance(int $tolerance): ImageRequestBuilder

Set safety filtering level.

Values:

• 0 - Strictest filtering
• 2 - Balanced (default)
• 6 - Most lenient

withOutputFormat(OutputFormat $format): ImageRequestBuilder

Set output format using enum.

asJpeg(): ImageRequestBuilder

Set output format to JPEG (shorthand method).

asPng(): ImageRequestBuilder

Set output format to PNG (shorthand method).

withWebhook(string $url, ?string $secret = null): ImageRequestBuilder

Configure webhook for result delivery.

Parameters:

• url (string) - Webhook URL
• secret (string, optional) - Secret for webhook verification

Build Methods

buildFlux1Pro(): Flux1ProRequest

Build a typed request object for FLUX1 Pro generation.

buildArray(): array

Build a generic parameter array for other model types.

Example:

Response Objects

ImageGenerationResponse

Returned by all image generation methods.

Properties:

• id (string) - Task identifier for polling

Methods:

• Access task ID for polling: $response->id

GetResultResponse

Returned by utility methods for task results.

Properties:

• id (string) - Task identifier
• status (ResultStatus) - Current task status
• result (mixed) - Task result when complete

Status Methods:

• isComplete(): bool - Check if task is finished
• isSuccessful(): bool - Check if task completed successfully
• isFailed(): bool - Check if task failed
• isInProgress(): bool - Check if task is still processing

Result Methods:

• getResultAsString(): ?string - Get result as string (typically image URL)
• getResultAsArray(): ?array - Get result as array
• getProgressPercentage(): ?float - Get progress percentage if available

Example:

Requirements

• PHP 8.1 or higher
• Guzzle HTTP client 7.0+
• JSON extension

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Testing & Quality Assurance

This package includes comprehensive testing across multiple PHP versions and dependency combinations.

Local Testing

CI/CD Pipeline

The package is automatically tested using GitHub Actions across:

• PHP Versions: 8.1, 8.2, 8.3
• Dependencies: prefer-lowest and prefer-stable
• Code Quality: PHPStan (max level), PHP CS Fixer
• Security: Composer audit and security advisories

Test Coverage

• 100+ Unit Tests: All components individually tested
• Integration Tests: End-to-end workflow validation
• Mock-based: Zero real API calls during testing
• Multiple Scenarios: Success, error, and edge cases

Quality Gates

All PRs must pass:

• ✅ Tests on all PHP versions
• ✅ Static analysis (PHPStan level max)
• ✅ Code style (PSR-12 + custom rules)
• ✅ Security audit
• ✅ No known vulnerabilities

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation
• Issues
• Black Forest Labs API Docs

Disclaimer

This is an unofficial SDK for Black Forest Labs' FLUX API. It is not affiliated with or endorsed by Black Forest Labs.

Made with ❤️ by l4nos