HeySwap

API Documentation

Welcome to the HeySwap API! Our RESTful API allows you to integrate our powerful AI image editing tools directly into your applications, websites, and workflows. Whether you're removing backgrounds, swapping models, or enhancing images, our API provides a simple and robust interface to get the job done.

To get started, you'll need an API key from your HeySwap account dashboard. All API requests must be authenticated using a JWT token, which you can obtain using your API key.

Authentication

Our API uses JWT (JSON Web Tokens) for authentication. It's a two-step process:

  1. Obtain a short-lived `access_token` by providing your permanent API key.
  2. Include this `access_token` in the `Authorization` header of all subsequent API requests as a Bearer token.

Tokens expire after 1 hour (3600 seconds). You should refresh your token before it expires to maintain a seamless connection.

Step 1: Get Access Token

Make a POST request to the `/api/token` endpoint with your API key.


curl -H 'Content-Type: application/json' \
     -d '{ "key":"YOUR_API_KEY" }' \
     -X POST \
     https://heyswap.pro/api/token

A successful response will return an `access_token`:


{
  "access_token": "JWT_AUTH_TOKEN"
}

Step 2: Refresh Access Token

To get a new token before the old one expires, call the `/api/refresh` endpoint.


curl -X POST https://heyswap.pro/api/refresh \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer YOUR_CURRENT_JWT_AUTH_TOKEN"

The response will provide a new token and its expiry time.


{
  "access_token": "NEW_JWT_AUTH_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600
}

Endpoints

Once authenticated, you can start making requests to our API endpoints. The base URL for all v1 endpoints is `https://heyswap.pro/api/v1/`.

Remove Background

POST /image/remove-background

This endpoint removes the background from a given image. You must provide a publicly accessible URL to the image.

Parameters

  • input_image (string, required): The URL of the source image.
  • output_format (string, optional): The desired output format. Can be `png`, `jpg`, or `webp`. Defaults to `png`.
  • bg_color (string, optional): Background color in hex format (e.g., "#2ec27e"). Overrides bg_gradient and gradient_direction when set.
  • bg_gradient (string, optional): Background gradient with two colors separated by colon (e.g., "#a855f7:#ec4899").
  • gradient_direction (enum, optional): Gradient direction. Options: `vertical`, `horizontal`, `diagonal-tl-br`, `diagonal-bl-tr`.
Background Parameter Notes:
  • If bg_color is set, it overrides bg_gradient and gradient_direction
  • If output format is jpg and no bg_color or bg_gradient is set, bg_color defaults to #ffffff

Example Request


# Basic request
curl -X POST https://heyswap.pro/api/v1/image/remove-background \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer JWT_AUTH_TOKEN" \
     -d '{ "input_image":"https://example.com/image.jpg", "output_format":"png" }'

# With solid background color
curl -X POST https://heyswap.pro/api/v1/image/remove-background \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer JWT_AUTH_TOKEN" \
     -d '{ "input_image":"https://example.com/image.jpg", "output_format":"jpg", "bg_color":"#2ec27e" }'

# With gradient background
curl -X POST https://heyswap.pro/api/v1/image/remove-background \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer JWT_AUTH_TOKEN" \
     -d '{ "input_image":"https://example.com/image.jpg", "bg_gradient":"#a855f7:#ec4899", "gradient_direction":"diagonal-tl-br" }'

Example Response


{
  "success": true,
  "message": "Background removed successfully",
  "data": {
    "output_image": "https://cdn.heyswap.pro/image/path/to/your/image.png",
    "input_image": "https://example.com/image.jpg"
  },
  "credits_remaining": 83
}

Check Credits

GET /user/credits

Retrieves the current credit balance for the authenticated user.

Example Request


curl https://heyswap.pro/api/v1/user/credits \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer JWT_AUTH_TOKEN"

Example Response


{
  "success": true,
  "credits": 84,
  "user_id": 1
}

Code Examples

Here are some examples of how to use our API in different programming languages.


async function removeBackground(imageUrl, authToken, options = {}) {
  const apiUrl = 'https://heyswap.pro/api/v1/image/remove-background';

  const payload = {
    input_image: imageUrl,
    output_format: options.output_format || 'png',
    ...options
  };

  const response = await fetch(apiUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${authToken}`
    },
    body: JSON.stringify(payload)
  });

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

  return await response.json();
}

// Usage examples
const jwtToken = 'YOUR_JWT_AUTH_TOKEN';
const imageUrl = 'https://example.com/your-product.jpg';

// Basic usage
removeBackground(imageUrl, jwtToken)
  .then(result => console.log('Success:', result))
  .catch(error => console.error('Error:', error));

// With solid background
removeBackground(imageUrl, jwtToken, { bg_color: '#2ec27e' })
  .then(result => console.log('Success:', result))
  .catch(error => console.error('Error:', error));

// With gradient background
removeBackground(imageUrl, jwtToken, {
  bg_gradient: '#a855f7:#ec4899',
  gradient_direction: 'diagonal-tl-br'
})
  .then(result => console.log('Success:', result))
  .catch(error => console.error('Error:', error));


import requests
import json

def remove_background(image_url, auth_token, **kwargs):
    api_url = "https://heyswap.pro/api/v1/image/remove-background"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {auth_token}"
    }
    payload = {
        "input_image": image_url,
        "output_format": kwargs.get("output_format", "png"),
        **kwargs
    }

    response = requests.post(api_url, headers=headers, data=json.dumps(payload))
    response.raise_for_status()
    return response.json()

# Usage examples
jwt_token = "YOUR_JWT_AUTH_TOKEN"
image_url = "https://example.com/your-product.jpg"

try:
    # Basic usage
    result = remove_background(image_url, jwt_token)
    print("Success:", result)
    
    # With solid background
    result = remove_background(image_url, jwt_token, bg_color="#2ec27e")
    print("Success:", result)
    
    # With gradient background
    result = remove_background(
        image_url, 
        jwt_token, 
        bg_gradient="#a855f7:#ec4899", 
        gradient_direction="diagonal-tl-br"
    )
    print("Success:", result)
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")


<?php

function removeBackground($imageUrl, $authToken, $options = []) {
    $apiUrl = 'https://heyswap.pro/api/v1/image/remove-background';

    $payload = array_merge([
        'input_image' => $imageUrl,
        'output_format' => 'png'
    ], $options);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $authToken
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode >= 400) {
        throw new Exception("HTTP error! status: $httpCode, response: $response");
    }

    return json_decode($response, true);
}

// Usage examples
$jwtToken = 'YOUR_JWT_AUTH_TOKEN';
$imageUrl = 'https://example.com/your-product.jpg';

try {
    // Basic usage
    $result = removeBackground($imageUrl, $jwtToken);
    print_r($result);
    
    // With solid background
    $result = removeBackground($imageUrl, $jwtToken, ['bg_color' => '#2ec27e']);
    print_r($result);
    
    // With gradient background
    $result = removeBackground($imageUrl, $jwtToken, [
        'bg_gradient' => '#a855f7:#ec4899',
        'gradient_direction' => 'diagonal-tl-br'
    ]);
    print_r($result);
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

?>


# Get auth token
AUTH_TOKEN=$(curl -s -H 'Content-Type: application/json' \
  -d '{ "key":"YOUR_API_KEY" }' \
  -X POST https://heyswap.pro/api/token | jq -r .access_token)

# Basic remove background
curl -X POST https://heyswap.pro/api/v1/image/remove-background \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -d '{ "input_image":"https://example.com/image.jpg" }'

# With solid background color
curl -X POST https://heyswap.pro/api/v1/image/remove-background \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -d '{ "input_image":"https://example.com/image.jpg", "bg_color":"#2ec27e" }'

# With gradient background
curl -X POST https://heyswap.pro/api/v1/image/remove-background \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -d '{ "input_image":"https://example.com/image.jpg", "bg_gradient":"#a855f7:#ec4899", "gradient_direction":"diagonal-tl-br" }'