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​

Alternative: Use public URLs

You can reference public HTTP(S) image or video URLs directly in your configuration instead of uploading first. The URL must end with a supported extension:

  • Images: .png, .jpg, .jpeg
  • Videos: .mp4, .webm, .mov

During job creation, JsonCut downloads, validates, uploads, and rewrites these URLs to secure relative paths automatically. Fonts are excluded from public URL support.

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!