curl --request POST \
--url https://api.apimart.ai/v1/uploads/images \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/your/image.jpg'
import requests
# Upload image
with open('image.jpg', 'rb') as f:
response = requests.post(
"https://api.apimart.ai/v1/uploads/images",
headers={
"Authorization": "Bearer <token>"
},
files={
"file": f
}
)
result = response.json()
image_url = result['url']
print(f"Image URL: {image_url}")
# Use the uploaded image for generation
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
json={
"model": "gemini-3-pro-image-preview",
"prompt": "Create a variation based on this image",
"image_urls": [{"url": image_url}]
}
)
// Upload image
const formData = new FormData();
formData.append('file', fileInput.files[0]);
const uploadResponse = await fetch('https://api.apimart.ai/v1/uploads/images', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>'
},
body: formData
});
const uploadResult = await uploadResponse.json();
const imageUrl = uploadResult.url;
console.log(`Image URL: ${imageUrl}`);
// Use the uploaded image for generation
const genResponse = await fetch('https://api.apimart.ai/v1/images/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gemini-3-pro-image-preview',
prompt: 'Create a variation based on this image',
image_urls: [{url: imageUrl}]
})
});
{
"url": "https://upload.apimart.ai/f/image/9990000123456-a1b2c3d4-photo.jpg",
"filename": "photo.jpg",
"content_type": "image/jpeg",
"bytes": 235680,
"created_at": 1743436800
}
{
"error": {
"message": "missing or invalid file field: http: no such file",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "unsupported image type: application/pdf, allowed: jpeg, png, gif, webp",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "file size 25165824 exceeds maximum 20971520 bytes",
"type": "invalid_request_error"
}
}
{
"error": {
"code": 429,
"message": "Rate limit exceeded. Please try again later",
"type": "rate_limit_error"
}
}
{
"error": {
"message": "failed to upload image",
"type": "server_error"
}
}
Upload Management
Upload Image
Upload an image to get a URL for use with image/video generation APIs
POST
/
v1
/
uploads
/
images
curl --request POST \
--url https://api.apimart.ai/v1/uploads/images \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/your/image.jpg'
import requests
# Upload image
with open('image.jpg', 'rb') as f:
response = requests.post(
"https://api.apimart.ai/v1/uploads/images",
headers={
"Authorization": "Bearer <token>"
},
files={
"file": f
}
)
result = response.json()
image_url = result['url']
print(f"Image URL: {image_url}")
# Use the uploaded image for generation
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
json={
"model": "gemini-3-pro-image-preview",
"prompt": "Create a variation based on this image",
"image_urls": [{"url": image_url}]
}
)
// Upload image
const formData = new FormData();
formData.append('file', fileInput.files[0]);
const uploadResponse = await fetch('https://api.apimart.ai/v1/uploads/images', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>'
},
body: formData
});
const uploadResult = await uploadResponse.json();
const imageUrl = uploadResult.url;
console.log(`Image URL: ${imageUrl}`);
// Use the uploaded image for generation
const genResponse = await fetch('https://api.apimart.ai/v1/images/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gemini-3-pro-image-preview',
prompt: 'Create a variation based on this image',
image_urls: [{url: imageUrl}]
})
});
{
"url": "https://upload.apimart.ai/f/image/9990000123456-a1b2c3d4-photo.jpg",
"filename": "photo.jpg",
"content_type": "image/jpeg",
"bytes": 235680,
"created_at": 1743436800
}
{
"error": {
"message": "missing or invalid file field: http: no such file",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "unsupported image type: application/pdf, allowed: jpeg, png, gif, webp",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "file size 25165824 exceeds maximum 20971520 bytes",
"type": "invalid_request_error"
}
}
{
"error": {
"code": 429,
"message": "Rate limit exceeded. Please try again later",
"type": "rate_limit_error"
}
}
{
"error": {
"message": "failed to upload image",
"type": "server_error"
}
}
The doc Playground does not support file uploads: Please use the cURL, Python, or JavaScript code examples below to test.
Important Change: For better performance and cost control, we no longer support passing base64 image data directly in generation APIs. Please use this API to upload images, get the URL, and then call the generation API.
Why upload images first?
- Performance Optimization - base64 encoding inflates data by 33%, uploading first significantly reduces request body size
- Reuse Images - Upload once, reuse the URL multiple times without redundant transfers
Workflow
curl --request POST \
--url https://api.apimart.ai/v1/uploads/images \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/your/image.jpg'
import requests
# Upload image
with open('image.jpg', 'rb') as f:
response = requests.post(
"https://api.apimart.ai/v1/uploads/images",
headers={
"Authorization": "Bearer <token>"
},
files={
"file": f
}
)
result = response.json()
image_url = result['url']
print(f"Image URL: {image_url}")
# Use the uploaded image for generation
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
json={
"model": "gemini-3-pro-image-preview",
"prompt": "Create a variation based on this image",
"image_urls": [{"url": image_url}]
}
)
// Upload image
const formData = new FormData();
formData.append('file', fileInput.files[0]);
const uploadResponse = await fetch('https://api.apimart.ai/v1/uploads/images', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>'
},
body: formData
});
const uploadResult = await uploadResponse.json();
const imageUrl = uploadResult.url;
console.log(`Image URL: ${imageUrl}`);
// Use the uploaded image for generation
const genResponse = await fetch('https://api.apimart.ai/v1/images/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gemini-3-pro-image-preview',
prompt: 'Create a variation based on this image',
image_urls: [{url: imageUrl}]
})
});
{
"url": "https://upload.apimart.ai/f/image/9990000123456-a1b2c3d4-photo.jpg",
"filename": "photo.jpg",
"content_type": "image/jpeg",
"bytes": 235680,
"created_at": 1743436800
}
{
"error": {
"message": "missing or invalid file field: http: no such file",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "unsupported image type: application/pdf, allowed: jpeg, png, gif, webp",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "file size 25165824 exceeds maximum 20971520 bytes",
"type": "invalid_request_error"
}
}
{
"error": {
"code": 429,
"message": "Rate limit exceeded. Please try again later",
"type": "rate_limit_error"
}
}
{
"error": {
"message": "failed to upload image",
"type": "server_error"
}
}
Authorizations
string
required
All APIs require Bearer Token authenticationGet API Key:Visit API Key Management Page to get your API KeyAdd to request headers:
Authorization: Bearer YOUR_API_KEY
Body
file
required
Image fileSupported formats: JPEG (.jpg, .jpeg), PNG (.png), WebP (.webp), GIF (.gif)Maximum file size: 20MB
Response
string
Public access URL for the image, can be used directly in generation APIs (valid for 72 hours)
string
Original file name
string
Detected MIME type, e.g.
image/jpeginteger
File size in bytes
integer
Upload time as Unix timestamp (seconds)
Full Example: Image-to-Image Workflow
Python
import requests
import time
API_KEY = "your-Apimart-key"
BASE_URL = "https://api.apimart.ai"
# Step 1: Upload reference image
def upload_image(file_path):
with open(file_path, 'rb') as f:
response = requests.post(
f"{BASE_URL}/v1/uploads/images",
headers={"Authorization": f"Bearer {API_KEY}"},
files={"file": f}
)
return response.json()['url']
# Step 2: Create generation task
def create_generation(image_url, prompt):
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"model": "gemini-3-pro-image-preview",
"prompt": prompt,
"image_urls": [{"url": image_url}],
"size": "16:9"
}
)
return response.json()['id']
# Step 3: Poll task status
def wait_for_result(task_id):
while True:
response = requests.get(
f"{BASE_URL}/v1/images/generations/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"}
)
result = response.json()
if result['status'] == 'completed':
return result['url']
elif result['status'] == 'failed':
raise Exception(f"Generation failed: {result.get('fail_reason')}")
time.sleep(2)
# Execute workflow
image_url = upload_image("reference.jpg")
print(f"Image uploaded: {image_url}")
task_id = create_generation(image_url, "Transform this photo into Ghibli anime style")
print(f"Task created: {task_id}")
result_url = wait_for_result(task_id)
print(f"Generation complete: {result_url}")
⌘I