Name: DDColor – Colorize B&W Photos | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-photorealistic-image-colorization-api
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 🌈 Photorealistic Image Colorization API (DDColor)

## Overview
The Photorealistic Image Colorization API (DDColor) enables you to transform grayscale or black-and-white images into vivid, lifelike color images. This API uses advanced deep-learning techniques with dual decoders to achieve high-fidelity colorization results quickly and accurately.

By using this service, you can effortlessly revitalize historical photos, enhance grayscale images for marketing or social media content, and transform monotone visuals into attention-grabbing colored designs.

## Features
- Dual-decoder AI model for improved color fidelity
- High-resolution colorization results
- Multiple model sizes (“large” and “tiny”) to accommodate performance and quality requirements
- Fast inference time for an efficient workflow
- HTTP-based asynchronous API for easy integration

## Use Cases
1. Historical Photo Restoration:
   - Bring old family photos back to life by adding realistic color.
2. Archival and Museum Collections:
   - Enhance archival materials without manual colorization efforts.
3. Creative Media & Advertising:
   - Refine monochrome visuals into marketing-ready content.
4. Content Creation for Social Media:
   - Quickly transform black-and-white posts into vibrant, engaging images.
5. Scientific and Research Visualization:
   - Colorize grayscale images for clearer analysis and presentation.

## Examples

Below are some examples demonstrating how the API can be used to colorize black-and-white images. 

### Input Image
Here is a historical black-and-white photo of a bank in Buffalo, NY, circa 1908:

![Historical black & white photo of a bank in Buffalo, NY circa 1908](https://replicate.delivery/pbxt/KDMkjS4SpsGieAxMdkBUNWT5zFI8BvAU4XjiyI2xmLny3skZ/Buffalo%20Bank%20Buffalo%2C%20New%20York%2C%20circa%201908.%20Erie%20County%20Savings%20Bank%2C%20Niagara%20Street.jpg)

### Output Image
After processing through the colorization API, the result is a photorealistic color image:

![Colorized version of the historical bank photo](https://replicate.delivery/pbxt/ZumJoHeMlA0WVyesmCZlkoKtNPakny5ariWAaXR3aEhvflXkA/out.png)

## Pricing
• 1 API unit = 1 image processed  
• GET requests (checking prediction status) are free and do not count toward API unit usage  
• Multiple pricing tiers are available, allowing you to scale usage according to your needs  

Contact the API.market team for detailed pricing information or visit the pricing section on API.market.

## API Documentation

### Base URL
All API requests should be made to:
```
https://prod.api.market/api/v1/magicapi/photorealistic-image-colorization-api
```

### Authentication
All requests must include your API key in the request header:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API processes colorization requests asynchronously. The typical flow is:

1. Submit a prediction request to the POST endpoint.  
2. Receive a prediction ID in the response (status will initially be "starting").  
3. Poll the GET endpoint with the prediction ID to check its status.  
4. When the status is "succeeded," your colorized image is ready.  

The processing time will depend on the complexity of the request. Implement a polling interval of about 1 second between status checks, and use a timeout (e.g., 10 minutes) to ensure your application doesn’t wait indefinitely.

### Endpoints

#### 1. Create a Prediction
• Endpoint:  
  ```
  POST /api/v1/magicapi/photorealistic-image-colorization-api/predictions
  ```
• Description:  
  Starts a new colorization job for a given grayscale image.

• Request Body Example:
```json
{
  "version": "ca494ba129e44e45f661d6ece83c4c98a9a7c774309beca01429b58fce8aa695",
  "input": {
    "image": "https://replicate.delivery/pbxt/KDMkjS4SpsGieAxMdkBUNWT5zFI8BvAU4XjiyI2xmLny3skZ/Buffalo%20Bank%20Buffalo%2C%20New%20York%2C%20circa%201908.%20Erie%20County%20Savings%20Bank%2C%20Niagara%20Street.jpg",
    "model_size": "large"
  }
}
```

• Response (201 Created) Example:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "ca494ba129e44e45f661d6ece83c4c98a9a7c774309beca01429b58fce8aa695",
  "status": "starting",
  "created_at": "2025-04-21T10:44:15.235Z"
}
```
  
#### 2. Get Prediction Status and Results
• Endpoint:  
  ```
  GET /api/v1/magicapi/photorealistic-image-colorization-api/predictions/{id}
  ```
• Description:  
  Retrieves the status and, if completed, the output (colorized image URL) for a previously submitted prediction.

• Response (200 OK) Example:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/pbxt/ZumJoHeMlA0WVyesmCZlkoKtNPakny5ariWAaXR3aEhvflXkA/out.png",
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

## Status Codes
• 200 OK: Request successful  
• 201 Created: Resource successfully created  
• 400 Bad Request: Invalid request parameters or missing fields  
• 401 Unauthorized: Missing or invalid API key  
• 403 Forbidden: The API key does not have the required permissions  
• 404 Not Found: The requested resource does not exist  
• 429 Too Many Requests: Rate limit exceeded; try again later  
• 500 Internal Server Error: An unexpected error occurred on the server side  
• 503 Service Unavailable: Temporary downtime or maintenance  

## Rate Limits
The service enforces rate limits to ensure stable performance for all customers. If you exceed the allowed request rate, you will receive an HTTP 429 error (Too Many Requests). To handle rate limits:
- Implement exponential backoff when retrying requests.
- Monitor response headers and error codes to determine if you should slow down or wait before retrying.

## Error Handling
When an error occurs, the API will return a JSON response with an error object that may contain:
- A code describing the type of error
- A message explaining the issue
- The status code

Example:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```

Guidelines for handling errors:
- Check the HTTP status code to determine the error category.
- Parse the response body to retrieve the error message.
- Use retry logic for transient errors (such as network issues).
- For 4xx errors, fix the request parameters before retrying.
- For 5xx errors, implement a short delay and retry.

## Implementation Guide

### Example Code

Below are code snippets illustrating how to integrate with this API:

#### JavaScript (Node.js) Example
```javascript
const fetch = require("node-fetch");

const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/photorealistic-image-colorization-api";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "ca494ba129e44e45f661d6ece83c4c98a9a7c774309beca01429b58fce8aa695",
        input: inputData
      })
    });

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

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 10 minutes
  const POLL_INTERVAL = 1000; // 1 second

  const startTime = Date.now();

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

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

    const prediction = await response.json();

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

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

    await delay(POLL_INTERVAL);
  }

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

// Example usage
(async () => {
  const result = await createAndWaitForPrediction({
    image: "https://replicate.delivery/pbxt/KDMkjS4SpsGieAxMdkBUNWT5zFI8BvAU4XjiyI2xmLny3skZ/Buffalo%20Bank%20Buffalo%2C%20New%20York%2C%20circa%201908.%20Erie%20County%20Savings%20Bank%2C%20Niagara%20Street.jpg",
    model_size: "large"
  });
  console.log("Colorized image URL:", result);
})();
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/photorealistic-image-colorization-api"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    payload = {
        "version": "ca494ba129e44e45f661d6ece83c4c98a9a7c774309beca01429b58fce8aa695",
        "input": input_data
    }

    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json=payload)
    
    if response.status_code not in [200, 201]:
        raise Exception(f"API error: {response.status_code} {response.text}")

    prediction = response.json()
    prediction_id = prediction["id"]

    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 10 minutes
    POLL_INTERVAL = 1  # 1 second

    headers = {"x-magicapi-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"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")

        time.sleep(POLL_INTERVAL)

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

# Example usage
if __name__ == "__main__":
    input_data = {
        "image": "https://replicate.delivery/pbxt/KDMkjS4SpsGieAxMdkBUNWT5zFI8BvAU4XjiyI2xmLny3skZ/Buffalo%20Bank%20Buffalo%2C%20New%20York%2C%20circa%201908.%20Erie%20County%20Savings%20Bank%2C%20Niagara%20Street.jpg",
        "model_size": "large"
    }
    print("Submitting prediction...")
    colorized_url = create_and_wait_for_prediction(input_data)
    print("Colorized image URL:", colorized_url)
```

#### cURL Example
```bash
# 1. Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/photorealistic-image-colorization-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ca494ba129e44e45f661d6ece83c4c98a9a7c774309beca01429b58fce8aa695",
    "input": {
      "image": "https://replicate.delivery/pbxt/KDMkjS4SpsGieAxMdkBUNWT5zFI8BvAU4XjiyI2xmLny3skZ/Buffalo%20Bank%20Buffalo%2C%20New%20York%2C%20circa%201908.%20Erie%20County%20Savings%20Bank%2C%20Niagara%20Street.jpg",
      "model_size": "large"
    }
  }'

# Sample response (with an example prediction ID):
# {
#   "id": "ufawqhfynnddngldkgtslldrkq",
#   "status": "starting",
#   "created_at": "2025-04-21T10:44:15.235Z"
# }

# 2. Check prediction status
curl -X GET "https://prod.api.market/api/v1/magicapi/photorealistic-image-colorization-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

## Performance Optimization
- Use the “tiny” model size for faster (though lower resolution) results.
- Only poll the prediction endpoint every 1–2 seconds to avoid unnecessary calls.
- Cancel a request if you no longer need the result, freeing up your application resources.

## FAQ
1. **How long does a single prediction take?**  
   Typically, predictions complete within a few seconds to a minute for standard images. This can vary based on image resolution, model size, and system load.

2. **Can I submit multiple predictions simultaneously?**  
   Yes, you can. Ensure that you track each prediction’s ID and poll them individually.

3. **What is the maximum image size I can upload?**  
   The maximum size depends on your pricing tier and performance considerations. If you encounter errors with large images, try reducing the resolution.

4. **How do I handle failed predictions?**  
   If a prediction returns a “failed” status, inspect the “error” field in the response for more details. Correct any issues and retry the request.

5. **Is the colorization process fully automated?**  
   Yes. The underlying model automatically infers the most plausible colors but does not guarantee 100% historic accuracy. You can retouch or adjust the results manually if needed.

## 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[at]api.market.

Automatically colorize black-and-white photos with a dual-decoder AI. Get vivid, high-fidelity results fast. From $0.05/call. Try it free on API.market.