Name: FLUX.1 Canny [pro] Edge-Guided Image API
Brand: magicapi
SKU: api-magicapi-edge-guided-image-generation-black-forest-labs-flux-canny-pro
Availability: InStock
Author: API Market

Shashank Agarwal

# ✂️ Professional Edge-Guided Image Generator API (FLUX.1 Canny [pro])

## Overview
FLUX.1 Canny [pro] is a professional edge-guided image generation model from Black Forest Labs. You send a text `prompt` and a `control_image`. The model uses Canny edge detection on the control image to control the structure and composition of the new image, and your prompt sets the content and style.

Both `prompt` and `control_image` are required. Each request returns the URL of one image.

## Features
- **Edge-guided generation**: the outlines of `control_image` set the structure and composition of the result.
- **Prompt control**: describe the content and style you want inside that structure.
- **Guidance** from 1 to 100 (default 30). Higher values follow the prompt more closely but may reduce image quality; lower values allow more creative freedom.
- **Steps** from 15 to 50 (default 50). More steps give finer detail but take longer.
- **Prompt upsampling**: `prompt_upsampling` modifies the prompt automatically for more creative results (default `false`).
- **Safety tolerance** from 1 (most strict) to 6 (most permissive), default 2.
- **Seed**: set a seed to reproduce a result.
- **Output formats**: `jpg` (default) or `png`.

## Use Cases
1. **Restyling with a fixed composition**: keep the layout of a photo or sketch and change its subject, material or style.
2. **Sketch to image**: turn a line drawing into a finished image that follows its outlines.
3. **Consistent product and scene variants**: produce several looks for the same composition by changing only the prompt.
4. **Character and pose reuse**: keep a figure's outline while changing its appearance.

## Visual Examples
### Example Input
Prompt: "A shiny chrome robot astronaut on the moon surface, stars in the sky"

Control image (`control_image`): [view the input image](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp)

All other fields were left at their defaults.

### Example Output
![FLUX.1 Canny pro output: a chrome robot astronaut on the moon following the outline of the control image](https://blog.api.market/wp-content/uploads/2026/10/flux-canny-pro-output-api-market.jpg)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `control_image` | string (URL) | Yes |  |  | Image to use as control input. Must be jpeg, png, gif, or webp. |
| `guidance` | number | No | `30` | 1 to 100 | Controls the balance between adherence to the text as well as image prompt and image quality/diversity. Higher values make the output more closely match the prompt but may reduce overall image quality. Lower values allow for more creative freedom but might produce results less relevant to the prompt. |
| `prompt` | string | Yes |  |  | Text prompt for image generation |
| `prompt_upsampling` | boolean | No | `false` |  | Automatically modify the prompt for more creative generation |
| `safety_tolerance` | integer | No | `2` | 1 to 6 | Safety tolerance, 1 is most strict and 6 is most permissive |
| `seed` | integer | No | none |  | Random seed. Set for reproducible generation |
| `steps` | integer | No | `50` | 15 to 50 | Number of diffusion steps. Higher values yield finer details but increase processing time. |
| `output_format` | string | No | `jpg` | `jpg`, `png` | Format of the output images. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.063 per API unit.
- **1 API unit = 1 output image.** Each request returns one image, so each successful request costs $0.063.
- Steps, guidance, output format and every other input setting are billed the same.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/edge-guided-image-generation-black-forest-labs-flux-canny-pro`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/edge-guided-image-generation-black-forest-labs-flux-canny-pro/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "835f0372c2cf4b2e494c2b8626288212ea5c2694ccc2e29f00dfb8cbf2a5e0ce",
    "input": {
      "prompt": "A shiny chrome robot astronaut on the moon surface, stars in the sky",
      "control_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "835f0372c2cf4b2e494c2b8626288212ea5c2694ccc2e29f00dfb8cbf2a5e0ce",
  "status": "starting",
  "created_at": "2026-10-13T10:49:52.821Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/edge-guided-image-generation-black-forest-labs-flux-canny-pro/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/flux-canny-pro-output-api-market.jpg",
  "error": null,
  "created_at": "2026-10-13T10:49:52.821Z",
  "started_at": "2026-10-13T10:49:53.821Z",
  "completed_at": "2026-10-13T10:50:06.821Z"
}
```

`output` is a single URL string pointing to the generated image.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `prompt` or `control_image`, or `steps` outside 15 to 50.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/edge-guided-image-generation-black-forest-labs-flux-canny-pro";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "835f0372c2cf4b2e494c2b8626288212ea5c2694ccc2e29f00dfb8cbf2a5e0ce", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
      "prompt": "A shiny chrome robot astronaut on the moon surface, stars in the sky",
      "control_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
  }).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/edge-guided-image-generation-black-forest-labs-flux-canny-pro"

def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "835f0372c2cf4b2e494c2b8626288212ea5c2694ccc2e29f00dfb8cbf2a5e0ce", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")

print(create_and_wait_for_prediction({
    "prompt": "A shiny chrome robot astronaut on the moon surface, stars in the sky",
    "control_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
}))
```

## FAQ
- **Do I need to make an edge map myself?**
  - The model description says it controls structure and composition using Canny edge detection. The example above sent an ordinary photo as `control_image`, and the output follows its outline.
- **Which image formats can I use for `control_image`?**
  - jpeg, png, gif or webp.
- **How do I make the result follow my prompt more closely?**
  - Raise `guidance`. Lower values give the model more creative freedom.
- **How many images does one request return?**
  - One. Each image is billed as one API unit ($0.063).
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


FLUX.1 Canny [pro] from Black Forest Labs generates images from a prompt while following the Canny edges of a control image. $0.063 per image, pay as you go.