This page covers all steps to integrate image generation APIs with text-to-image and image-to-image into your system.
Good to know: A quick start guide can be good to help folks get up and running with your API in a few steps. Some people prefer diving in with the basics rather than meticulously reading every page of documentation!
Get your API keys
Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.
You can generate an API key from your user dashboard in Miragic website anytime.
Authentication
All requests must include the X-API-Key header containing your assigned API key.
How To Create Image Generation Task
POST/api/v1/image/generate
This API starts the Image Generation process by creating a task that generates a stunning art images.
Processing Information
Tasks are processed asynchronously in the background
Progress can be monitored using the Get Task Status API
The final result will be a high-quality image
Request
Parameter
Type
Required
Description
prompt
String
Yes
Input text to demonstrate output image.
model
String
Yes
AI model option for image generation. The values can be flux, turbo, gptimage, and kontext.
width
Number
Yes
The valid value range is 256-2048
height
Number
Yes
The valid value range is 256-2048.
image_url
String
Optional
This value represents the URL of the input image for image-to-image tasks. It is only available when the model is set to kontext.
Request Example (Text-To-Image)
Request Example (Image-To-Image)
Response
Response Field
Field
Type
Description
jobId
String
A unique identifier used to track task status and retrieve results.
status
String
The initial status will be PENDING. Use the Get Task Status API to track progress.
message
String
To describe task status
success
Logic
true or false to indicate whether task is successful or not.
How To Get Task Status
GET/api/v1/image/jobs/:jobId
This API lets you check the status of a image generation task and retrieve the final result. Because the image generation process runs asynchronously, you’ll need to poll this endpoint until the task is finished.
Task Status:
Status
Description
Progress
Next Action
PENDING
Task is currently being processed.
0~99%
Continue polling
COMPLETED
Task has finished successfully.
100%
Download result using download_signed_url
FAILED
Task processing failed.
N/A
Check error details and retry if needed
Progress Tracking:
The progress field indicates the percentage of task completion (0-100)
Progress updates are available in real-time during the PENDING state
Progress increases as the AI processes different stages of the try-on task
Polling Guidelines:
Start polling immediately after creating the task
Implement exponential backoff to avoid rate limiting
The download_signed_url is temporary and should be used promptly
Consider implementing a timeout after extended polling
Request:
URL Parameters
Parameter
Type
Required
Description
JobId
String
Yes
This value indicates task ID assigned by requesting Image Generation process API
Request Example
Response Example
Completed Status (200):
Response Fields
Field
Type
Description
id
String
Unique identifier of the task
status
String
Current status of the task (PENDING/COMPLETED/FAILED)
userId
String
Unique identifier of the user
processedImageUrl
String
URL to result image
createdAt
Number
Unix timestamp when processing is created
errorMessage
String
Error message
Full Code Example
The following code lines are quick example to use our API in multiple languages.
curl -X POST "https://backend.miragic.ai/api/v1/image/generate" \
-H "X-API-Key: YOUR_API_KEY" \
-F "prompt=A beatiful sunset over the ocean" \
-F "model=flux" \
-F "width=2048" \
-F "height=1024"
import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";
const apiKey = "YOUR_API_KEY";
const baseUrl = "https://backend.miragic.ai";
async function image_gen() {
const url = `${baseUrl}/api/v1/image/generate`;
const formData = new FormData();
formData.append("prompt", "A beatiful sunset over the ocean");
formData.append("model", "flux");
formData.append("width", "2048");
formData.append("height", "1024");
const response = await fetch(url, {
method: "POST",
headers: {
"X-API-Key": apiKey,
...formData.getHeaders(),
},
body: formData,
});
const result = await response.text();
console.log(result);
}
image_gen();
import requests
import time
api_key = 'YOUR_API_KEY' # ← Replace with your actual API key
base_url = 'https://backend.miragic.ai'
def image_gen():
url = f'{base_url}/api/v1/image/generate'
data = {
'prompt': 'A beatiful sunset over the ocean', # Any text available
'model': 'flux', # 'flux', 'turbo', 'gptimage', 'kontext'
'width': 2048, # The valid value range is 256–2048
'height': 1024 # The valid value range is 256–2048
}
headers = {'X-API-Key': api_key}
response = requests.request("POST", url, headers=headers, data=data)
print(response.text)
if __name__ == '__main__':
image_gen()
curl -X POST "https://backend.miragic.ai/api/v1/image/generate" \
-H "X-API-Key: YOUR_API_KEY" \
-F "prompt=A beatiful sunset over the ocean" \
-F "model=flux" \
-F "width=2048" \
-F "height=1024"
import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";
const apiKey = "YOUR_API_KEY";
const baseUrl = "https://backend.miragic.ai";
async function image_gen() {
const url = `${baseUrl}/api/v1/image/generate`;
const formData = new FormData();
formData.append("prompt", "A beatiful sunset over the ocean");
formData.append("model", "flux");
formData.append("width", "2048");
formData.append("height", "1024");
const response = await fetch(url, {
method: "POST",
headers: {
"X-API-Key": apiKey,
...formData.getHeaders(),
},
body: formData,
});
const result = await response.text();
console.log(result);
}
image_gen();
import requests
import time
api_key = 'YOUR_API_KEY' # ← Replace with your actual API key
base_url = 'https://backend.miragic.ai'
def image_gen():
url = f'{base_url}/api/v1/image/generate'
data = {
'prompt': 'A beatiful sunset over the ocean', # Any text available
'model': 'flux', # 'flux', 'turbo', 'gptimage', 'kontext'
'width': 2048, # The valid value range is 256–2048
'height': 1024 # The valid value range is 256–2048
}
headers = {'X-API-Key': api_key}
response = requests.request("POST", url, headers=headers, data=data)
print(response.text)
if __name__ == '__main__':
image_gen()
curl -X POST "https://backend.miragic.ai/api/v1/image/generate" \
-H "X-API-Key: YOUR_API_KEY" \
-F "prompt=A beatiful sunset over the ocean" \
-F "model=flux" \
-F "width=2048" \
-F "height=1024" \
-F "image_url=https://images.tech.co/wp-content/uploads/2023/11/21202640/AI-generated-landscape-708x400.jpg"
import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";
const apiKey = "YOUR_API_KEY";
const baseUrl = "https://backend.miragic.ai";
async function image_gen() {
const url = `${baseUrl}/api/v1/image/generate`;
const formData = new FormData();
formData.append("prompt", "A beatiful sunset over the ocean");
formData.append("model", "flux");
formData.append("width", "2048");
formData.append("height", "1024");
formData.append("image_url", "https://images.tech.co/wp-content/uploads/2023/11/21202640/AI-generated-landscape-708x400.jpg");
const response = await fetch(url, {
method: "POST",
headers: {
"X-API-Key": apiKey,
...formData.getHeaders(),
},
body: formData,
});
const result = await response.text();
console.log(result);
}
image_gen();
import requests
import time
api_key = 'YOUR_API_KEY' # ← Replace with your actual API key
base_url = 'https://backend.miragic.ai'
def image_gen():
url = f'{base_url}/api/v1/image/generate'
data = {
'prompt': 'A beatiful sunset over the ocean', # Any text available
'model': 'flux', # 'flux', 'turbo', 'gptimage', 'kontext'
'width': 2048, # The valid value range is 256–2048
'height': 1024, # The valid value range is 256–2048
'image_url': 'https://images.tech.co/wp-content/uploads/2023/11/21202640/AI-generated-landscape-708x400.jpg'
}
headers = {'X-API-Key': api_key}
response = requests.request("POST", url, headers=headers, data=data)
print(response.text)
if __name__ == '__main__':
image_gen()
{"success":true,"data":{"jobId":"56ba3768-2195-464c-98cd-e9dc535c2258","status":"PENDING"},"message":"Image generation job created successfully"}
curl -X GET https://backend.miragic.ai/api/v1/image/jobs/25331fb2-d0b0-44f6fcc85e3e \
-H "X-API-Key: YOUR_API_KEY"
curl -X POST "https://backend.miragic.ai/api/v1/image/generate" \
-H "X-API-Key: YOUR_API_KEY" \
-F "prompt=A beatiful sunset over the ocean" \
-F "model=flux" \
-F "width=2048" \
-F "height=1024"
import axios from "axios";
import fs from "fs";
import FormData from "form-data";
const apiKey = "YOUR_API_KEY";
const baseUrl = "https://devapi.miragic.ai";
async function image_gen() {
const url = `${baseUrl}/api/v1/image/generate`;
// Form data with your settings
const form = new FormData();
formData.append("prompt", "A beatiful sunset over the ocean");
formData.append("model", "flux");
formData.append("width", "2048");
formData.append("height", "1024");
const headers = {
"X-API-Key": apiKey,
...form.getHeaders(),
};
try {
// Step 1: Create job
const response = await axios.post(url, form, { headers });
console.log(response.data);
if (response.data.success) {
const jobId = response.data.data.jobId;
console.log(`Job ID: ${jobId}`);
// Step 2: Poll for results
let status = "PENDING";
while (status !== "COMPLETED" && status !== "FAILED") {
await new Promise((r) => setTimeout(r, 2000)); // wait 2 sec
const result = await axios.get(`${baseUrl}/api/v1/image/jobs/${jobId}`, {
headers: { "X-API-Key": apiKey },
});
status = result.data.data.status;
if (status === "COMPLETED") {
console.log("Result:", result.data);
break;
} else if (status === "FAILED") {
console.log("Job failed:", result.data);
break;
} else {
console.log(`Current status: ${status}...`);
}
}
} else {
console.log("Error:", response.data);
}
} catch (error) {
console.error("Request failed:", error.response?.data || error.message);
}
}
image_gen();
import requests
import time
api_key = 'YOUR_API_KEY' # ← Replace with your actual API key
base_url = 'https://backend.miragic.ai'
def image_gen():
url = f'{base_url}/api/v1/image/generate'
data = {
'prompt': 'A beatiful sunset over the ocean', # Any text available
'model': 'flux', # 'flux', 'turbo', 'gptimage', 'kontext'
'width': 2048, # The valid value range is 256–2048
'height': 1024 # The valid value range is 256–2048
}
headers = {'X-API-Key': api_key}
response = requests.request("POST", url, headers=headers, data=data)
print(response.text)
if response.json()['success']:
job_id = response.json()['data']['jobId']
print(f'Job ID: {job_id}')
# Poll for results
while True:
result = requests.get(
f'{base_url}/api/v1/image/jobs/{job_id}',
headers=headers
)
if result.json()['data']['status'] == 'COMPLETED':
print('Result:', result.json())
break
elif result.json()['data']['status'] == 'FAILED':
print('Job failed:', result.json())
break
time.sleep(2)
else:
print('Error:', response.json())
if __name__ == '__main__':
image_gen()
curl -X POST "https://backend.miragic.ai/api/v1/image/generate" \
-H "X-API-Key: YOUR_API_KEY" \
-F "prompt=A beatiful sunset over the ocean" \
-F "model=flux" \
-F "width=2048" \
-F "height=1024" \
-F "image_url=https://images.tech.co/wp-content/uploads/2023/11/21202640/AI-generated-landscape-708x400.jpg"
import axios from "axios";
import fs from "fs";
import FormData from "form-data";
const apiKey = "YOUR_API_KEY";
const baseUrl = "https://devapi.miragic.ai";
async function image_gen() {
const url = `${baseUrl}/api/v1/image/generate`;
// Form data with your settings
const form = new FormData();
formData.append("prompt", "A beatiful sunset over the ocean");
formData.append("model", "flux");
formData.append("width", "2048");
formData.append("height", "1024");
formData.append("image_url", "https://images.tech.co/wp-content/uploads/2023/11/21202640/AI-generated-landscape-708x400.jpg");
const headers = {
"X-API-Key": apiKey,
...form.getHeaders(),
};
try {
// Step 1: Create job
const response = await axios.post(url, form, { headers });
console.log(response.data);
if (response.data.success) {
const jobId = response.data.data.jobId;
console.log(`Job ID: ${jobId}`);
// Step 2: Poll for results
let status = "PENDING";
while (status !== "COMPLETED" && status !== "FAILED") {
await new Promise((r) => setTimeout(r, 2000)); // wait 2 sec
const result = await axios.get(`${baseUrl}/api/v1/image/jobs/${jobId}`, {
headers: { "X-API-Key": apiKey },
});
status = result.data.data.status;
if (status === "COMPLETED") {
console.log("Result:", result.data);
break;
} else if (status === "FAILED") {
console.log("Job failed:", result.data);
break;
} else {
console.log(`Current status: ${status}...`);
}
}
} else {
console.log("Error:", response.data);
}
} catch (error) {
console.error("Request failed:", error.response?.data || error.message);
}
}
image_gen();
import requests
import time
api_key = 'YOUR_API_KEY' # ← Replace with your actual API key
base_url = 'https://backend.miragic.ai'
def image_gen():
url = f'{base_url}/api/v1/image/generate'
data = {
'prompt': 'A beatiful sunset over the ocean', # Any text available
'model': 'flux', # 'flux', 'turbo', 'gptimage', 'kontext'
'width': 2048, # The valid value range is 256–2048
'height': 1024, # The valid value range is 256–2048
'image_url': 'https://images.tech.co/wp-content/uploads/2023/11/21202640/AI-generated-landscape-708x400.jpg'
}
headers = {'X-API-Key': api_key}
response = requests.request("POST", url, headers=headers, data=data)
print(response.text)
if response.json()['success']:
job_id = response.json()['data']['jobId']
print(f'Job ID: {job_id}')
# Poll for results
while True:
result = requests.get(
f'{base_url}/api/v1/image/jobs/{job_id}',
headers=headers
)
if result.json()['data']['status'] == 'COMPLETED':
print('Result:', result.json())
break
elif result.json()['data']['status'] == 'FAILED':
print('Job failed:', result.json())
break
time.sleep(2)
else:
print('Error:', response.json())
if __name__ == '__main__':
image_gen()
