Skip to main content
POST
/
api
/
v1
/
upload
Upload Design
curl --request POST \
  --url https://api.example.com/api/v1/upload
{
  "id": "<string>",
  "url": "<string>",
  "thumbnailUrl": "<string>",
  "dimensions": {
    "width": 123,
    "height": 123
  },
  "fileSize": 123,
  "mimeType": "<string>"
}

​
Upload Design

Upload a design image and receive a URL for use with the /generate endpoint.
This endpoint is free — no tokens required.

​
Endpoint

POST https://garmint.app/api/v1/upload

​
Request Formats

​
Multipart Form Upload

Send the image as multipart/form-data: 
curl -X POST https://garmint.app/api/v1/upload \
  -H "Authorization: Bearer gm_live_xxx" \
  -F "file=@my-design.png"

​
Base64 JSON Upload

Send base64-encoded image data: 
curl -X POST https://garmint.app/api/v1/upload \
  -H "Authorization: Bearer gm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "imageData": "data:image/png;base64,iVBORw0KGgo..."
  }'

​
Constraints

ConstraintValue
Max file size10 MB
Allowed formatsPNG, JPEG, WebP, GIF
Recommended resolution2400x3000px or higher

​
Response

​
id
string
Unique upload identifier.
​
url
string
Public URL of the uploaded image. Use this with /generate.
​
thumbnailUrl
string
Smaller thumbnail version.
​
dimensions
object
​
fileSize
number
File size in bytes.
​
mimeType
string
Detected MIME type.

​
Example

curl -X POST https://garmint.app/api/v1/upload \
  -H "Authorization: Bearer gm_live_xxx" \
  -F "file=@my-design.png"

​
Response Example

{
  "id": "upl_1703001234_xyz789",
  "url": "https://res.cloudinary.com/garmint/image/upload/v123/api-uploads/xyz789.png",
  "thumbnailUrl": "https://res.cloudinary.com/garmint/image/upload/v123/api-uploads/xyz789.png",
  "dimensions": {
    "width": 2400,
    "height": 3000
  },
  "fileSize": 1548276,
  "mimeType": "image/png"
}

​
Full Workflow

Upload → Analyze → Generate: 
async function createMockup(file: File, garmentId: string) {
  // 1. Upload the design
  const formData = new FormData();
  formData.append('file', file);
  
  const uploadRes = await fetch('https://garmint.app/api/v1/upload', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_KEY}` },
    body: formData,
  });
  const upload = await uploadRes.json();
  
  // 2. Analyze (optional but recommended)
  const analyzeRes = await fetch('https://garmint.app/api/v1/analyze', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ imageUrl: upload.url }),
  });
  const analysis = await analyzeRes.json();
  
  if (analysis.warnings.length > 0) {
    console.warn('Design warnings:', analysis.warnings);
  }
  
  // 3. Generate mockup
  const generateRes = await fetch('https://garmint.app/api/v1/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      designUrl: upload.url,
      garmentId,
      garmentImageUrl: '...', // Get from /garments
      placement: { x: 50, y: 35, scale: 0.8 },
    }),
  });
  
  return generateRes.json();
}

​
Image Preparation Tips

PNG preserves alpha channels for transparent backgrounds, essential for printing on colored garments.
Upload at 300 DPI or higher. For a 12” wide print, that’s at least 3600px wide.
Ensure images are in sRGB color space for consistent color representation.
Trim transparent borders to get accurate placement calculations.

​
Errors

CodeStatusDescription
invalid_request400No file provided or invalid format
invalid_request400File too large (max 10MB)
invalid_request400Could not read image