Youzu Magic Background

The Youzu Magic Background Component enhances product images by adding appropriate backgrounds or removing them entirely.

API

The Magic Background API allows you to generate backgrounds for product images. You can either replace the background with another image or remove it entirely.

Authentication

You can authenticate using either:

Option 1: Authorization: Bearer YOUR_TOKEN header (obtain from /api/v1/token)

Option 2: x-client-secret: YOUR_CLIENT_SECRET header

Generate Magic Background

Endpoint: POST /api/v1/magic-background

Generate a magic background for a product image. You can provide either a file upload or a URL for both the product and optional background images.

curl -X POST "https://platform.youzu.ai/api/v1/magic-background" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "productImage=@product.jpg" \
  -F "backgroundImage=@background.jpg"

curl -X POST "https://platform.youzu.ai/api/v1/magic-background" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -F "productImage=@product.jpg" \
  -F "backgroundImage=@background.jpg"

// Generate magic background using token
const formData = new FormData();
formData.append('productImage', document.getElementById('product').files[0]);
formData.append('backgroundImage', document.getElementById('background').files[0]);

fetch('https://platform.youzu.ai/api/v1/magic-background', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  },
  body: formData
})
.then(response => response.json())
.then(data => {
  console.log('Background generation started:', data);
  // Poll for completion using data.id
})
.catch(error => {
  console.error('Error:', error);
});

// Generate magic background using client secret
const formData = new FormData();
formData.append('productImage', document.getElementById('product').files[0]);
formData.append('backgroundImage', document.getElementById('background').files[0]);

fetch('https://platform.youzu.ai/api/v1/magic-background', {
  method: 'POST',
  headers: {
    'x-client-secret': 'YOUR_CLIENT_SECRET'
  },
  body: formData
})
.then(response => response.json())
.then(data => {
  console.log('Background generation started:', data);
  // Poll for completion using data.id
})
.catch(error => {
  console.error('Error:', error);
});

import requests

# Generate magic background using token
url = 'https://platform.youzu.ai/api/v1/magic-background'

headers = {
    'Authorization': 'Bearer YOUR_TOKEN'
}

files = [
    ('productImage', open('product.jpg', 'rb')),
    ('backgroundImage', open('background.jpg', 'rb'))
]

response = requests.post(url, headers=headers, files=files)

if response.status_code == 200:
    job = response.json()
    print('Background generation started:', job)
    # Poll for completion using job['id']
else:
    print('Error:', response.status_code, response.text)

import requests

# Generate magic background using client secret
url = 'https://platform.youzu.ai/api/v1/magic-background'

headers = {
    'x-client-secret': 'YOUR_CLIENT_SECRET'
}

files = [
    ('productImage', open('product.jpg', 'rb')),
    ('backgroundImage', open('background.jpg', 'rb'))
]

response = requests.post(url, headers=headers, files=files)

if response.status_code == 200:
    job = response.json()
    print('Background generation started:', job)
    # Poll for completion using job['id']
else:
    print('Error:', response.status_code, response.text)

Get Job Status

Endpoint: GET /api/v1/magic-background/{id}

Check the status of a magic background generation job.

curl -X GET "https://platform.youzu.ai/api/v1/magic-background/YOUR_JOB_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X GET "https://platform.youzu.ai/api/v1/magic-background/YOUR_JOB_ID" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

// Check job status using token
fetch('https://platform.youzu.ai/api/v1/magic-background/YOUR_JOB_ID', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Job status:', data.status);
  if (data.status === 'COMPLETED') {
    console.log('Generated image URL:', data.outputUrls[0]);
  }
})
.catch(error => {
  console.error('Error:', error);
});

// Check job status using client secret
fetch('https://platform.youzu.ai/api/v1/magic-background/YOUR_JOB_ID', {
  method: 'GET',
  headers: {
    'x-client-secret': 'YOUR_CLIENT_SECRET'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Job status:', data.status);
  if (data.status === 'COMPLETED') {
    console.log('Generated image URL:', data.outputUrls[0]);
  }
})
.catch(error => {
  console.error('Error:', error);
});

import requests

# Check job status using token
url = 'https://platform.youzu.ai/api/v1/magic-background/YOUR_JOB_ID'

headers = {
    'Authorization': 'Bearer YOUR_TOKEN'
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    job = response.json()
    print('Job status:', job['status'])
    if job['status'] == 'COMPLETED':
        print('Generated image URL:', job['outputUrls'][0])
else:
    print('Error:', response.status_code, response.text)

import requests

# Check job status using client secret
url = 'https://platform.youzu.ai/api/v1/magic-background/YOUR_JOB_ID'

headers = {
    'x-client-secret': 'YOUR_CLIENT_SECRET'
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    job = response.json()
    print('Job status:', job['status'])
    if job['status'] == 'COMPLETED':
        print('Generated image URL:', job['outputUrls'][0])
else:
    print('Error:', response.status_code, response.text)

SDK

Props

Property	Attribute	Description	Type	Default
`alt`	`alt`	The alt text for the image	string	`''`
`apiEndpoint`	`api-endpoint`	The API endpoint for background processing	string	`'/api/background'`
`height`	`height`	The height of the image	string	`undefined`
`hideLoading`	`hide-loading`	Whether to disable the loading indicator	boolean	`false`
`mode`	`mode`	The mode to control background application behavior - auto: Ask server if background is needed, add if necessary - always: Always add a background - manual: No automatic requests, use applyBackground() method	`"always" \| "auto" \| "manual"`	`'auto'`
`showLoader`	`show-loader`	Manually control the loading state (for demo purposes)	boolean	`false`
`src`	`src`	The source URL of the image	string	`undefined`
`stylePreset`	`style-preset`	The style preset to use for the background Default is 'modern'	string	`'modern'`
`width`	`width`	The width of the image	string	`undefined`

Events

Event	Description	Type
`backgroundChange`	Event emitted when a background is applied or removed	`CustomEvent<BackgroundChangeEventData>`

Methods

Method	Parameters	Return Type	Description
`applyBackground`	`options?: BackgroundOptions`	`Promise<string>`	Public method to manually apply a background Can be called in manual mode

Youzu Fill

2D to 3D