Skip to main content

Quick Start Guide

This guide will walk you through creating your first media processing job with JsonCut. In just a few minutes, you'll upload a file, process it, and download the result.

Prerequisites​

  • A JsonCut account with an API key (sign up here)
  • Basic knowledge of HTTP requests
  • A command line tool like cURL (or use our examples in other languages)

Step 1: Upload a Source File​

First, let's upload an image that we'll use as the source for processing:

curl -L 'https://api.jsoncut.com/v1/files/upload' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'file=@"/path/to/your/image.jpg"' \
-F 'category="image"'

Response:

{
  "success": true,
  "data": {
    "id": "cmfaq4h2e000192jspdf1tv5m",
    "filename": "c798710a-e05b-4ceb-a575-3476494af832.png",
    "originalName": "example-image.png",
    "mimeType": "image/png",
    "storageUrl": "/image/2020-09-08/cmejszvz00000t5afm8qcr6bq/27f63059-57f5-48d1-a0a1-471c02d2cd45.png",
    "metadata": {
      "category": "image",
      "validationResult": {
        "errors": [],
        "isValid": true,
        "fileSize": 4342589,
        "detectedMimeType": "image/png"
      }
    },
    "createdAt": "2025-09-08T06:11:25.671Z"
  },
  "message": "File uploaded successfully"
}
Important

From the response above, save the storageUrl (/image/2020-09-08/... in this example) - this is what you'll use in your job configuration!

Step 2: Create a Simple Image Processing Job​

Now let's create a job that adds text to your uploaded image using the storageUrl from the upload response:

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "config": {
      "width": 1920,
      "height": 1080,
      "layers": [
        {
          "type": "image",
          "path": "/image/2020-09-08/cmejszvz00000t5afm8qcr6bq/27f63059-57f5-48d1-a0a1-471c02d2cd45.png",
          "position": "center"
        },
        {
          "type": "text",
          "text": "Hello from JsonCut!",
          "position": "center",
          "fontSize": 48,
          "color": "#000000"
        }
      ]
    }
  }' \
  https://api.jsoncut.com/v1/jobs

Response:

{
  "success": true,
  "data": {
    "jobId": "job_xyz789",
    "status": "PENDING",
    "type": "IMAGE",
    "estimatedTokens": 3,
    "createdAt": "2024-01-15T10:32:00Z"
  }
}

Step 3: Check Job Status​

Jobs are processed asynchronously. Check the status with:

curl -H "x-api-key: YOUR_API_KEY" \
     https://api.jsoncut.com/v1/jobs/job_xyz789

Response when processing:

{
  "success": true,
  "data": {
    "id": "job_xyz789",
    "type": "IMAGE", 
    "status": "PROCESSING",
    "tokensUsed": 0,
    "startedAt": "2024-01-15T10:32:05Z",
    "createdAt": "2024-01-15T10:32:00Z"
  }
}

Response when complete:

{
  "success": true,
  "data": {
    "id": "job_xyz789",
    "type": "IMAGE",
    "status": "COMPLETED",
    "outputFileId": "cmfaq4h2e000192jspdf1tv5n",
    "tokensUsed": 3,
    "completedAt": "2024-01-15T10:32:08Z",
    "createdAt": "2024-01-15T10:32:00Z"
  }
}

Step 4: Download Your Result​

Once the job is complete, use the outputFileId to download your processed image:

curl -H "x-api-key: YOUR_API_KEY" \
     -o result.jpg \
     https://api.jsoncut.com/v1/files/cmfaq4h2e000192jspdf1tv5n/download

🎉 Congratulations! You've successfully processed your first image with JsonCut!

What Just Happened?​

  1. File Upload: You uploaded your source image and received a storageUrl
  2. Job Creation: You created a job using the storageUrl in your configuration
  3. Processing: JsonCut processed your image according to your specifications
  4. Download: You used the outputFileId to download the final result

Error Handling​

If something goes wrong, the API will return an error:

{
  "success": false,
  "error": "File validation failed: File not found at path"
}

Common issues:

  • Invalid storageUrl: Make sure you're using the exact storageUrl from the upload response
  • Missing API key: Include the x-api-key header in all requests
  • Invalid configuration: Check that your layer configuration matches the expected format
  • Insufficient permissions: Ensure your API key has Full Access for creating jobs

Ready for More?​

Now that you've completed your first job, explore:

Questions? We're here to help at support@jsoncut.com!