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