HTTP API

REST API reference for custom PichaFlow integrations.

PichaFlow can be integrated into any language or framework that supports HTTP requests.

Base URL

The default API endpoint is: https://egn.pichaflow.com/v1

Authentication

All requests must include your Secret Key in the Authorization header as a Bearer token.

Authorization: Bearer sk_live_your_secret_key
Security Note: For server-to-server integrations, only the Authorization header is required.

Payload Limits & Pre-Optimization

To guarantee ultra-fast edge processing, the PichaFlow Edge Engine enforces a strict 5MB file size limit on all direct HTTP API uploads.

If you are uploading via a backend server (bypassing our frontend SDKs), you must compress your images down to a maximum of 2048px (ideally WebP) before making the POST request. Uploads exceeding 5MB will be rejected with a 413 Payload Too Large error.

1. Uploading Images (cURL)

curl -X POST https://egn.pichaflow.com/v1/upload \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@/path/to/your/image.jpg" \
  -F "tenantId=pf_prj_your_id" \
  -F "alt=Description for SEO" \
  -F "tags=[\"ecommerce\", \"summer\"]"

2. Python Integration

import requests

url = "https://egn.pichaflow.com/v1/upload"
headers = {
    "Authorization": "Bearer sk_live_your_secret_key"
}
files = {
    "file": open("product.jpg", "rb")
}
data = {
    "tenantId": "pf_prj_your_id",
    "alt": "Summer Collection Boot",
    "tags": "[\"ecommerce\"]"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

3. Node.js (Fetch)

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('tenantId', 'pf_prj_your_id');
formData.append('alt', 'Modern Sofa');

const response = await fetch('https://egn.pichaflow.com/v1/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_secret_key'
  },
  body: formData
});

const result = await response.json();

4. PHP Integration

$ch = curl_init('https://egn.pichaflow.com/v1/upload');
$cfile = new CURLFile('image.jpg', 'image/jpeg', 'file');

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'file' => $cfile,
    'tenantId' => 'pf_prj_your_id',
    'alt' => 'Luxury Watch'
]);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer sk_live_your_secret_key'
]);

$result = curl_exec($ch);
curl_close($ch);

5. Go Integration

package main

import (
    "bytes"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

func main() {
    file, _ := os.Open("image.jpg")
    defer file.Close()

    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    part, _ := writer.CreateFormFile("file", "image.jpg")
    io.Copy(part, file)
    writer.WriteField("tenantId", "pf_prj_your_id")
    writer.WriteField("alt", "Coffee Mug")
    writer.Close()

    req, _ := http.NewRequest("POST", "https://egn.pichaflow.com/v1/upload", body)
    req.Header.Set("Content-Type", writer.FormDataContentType())
    req.Header.Set("Authorization", "Bearer sk_live_your_secret_key")

    client := &http.Client{}
    client.Do(req)
}

6. Rust Integration

use reqwest::header::{AUTHORIZATION, HeaderValue};
use reqwest::multipart;
use std::fs;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let file_path = "image.jpg";
    let file_bytes = fs::read(file_path)?;

    let form = multipart::Form::new()
        .part("file", multipart::Part::bytes(file_bytes).file_name("image.jpg"))
        .text("tenantId", "pf_prj_your_id")
        .text("alt", "Titanium Wristwatch")
        .text("tags", "[\"luxury\", \"watch\"]");

    let response = client
        .post("https://egn.pichaflow.com/v1/upload")
        .header(AUTHORIZATION, HeaderValue::from_static("Bearer sk_live_your_secret_key"))
        .multipart(form)
        .send()
        .await?;

    println!("Status: {}", response.status());
    println!("Body: {}", response.text().await?);

    Ok(())
}

7. URL Transformations (Image Retrieval)

Once your image is uploaded, the PichaFlow Edge Engine allows you to transform it on the fly by appending URL parameters to the asset's URL. The engine caches the result at the edge for ultra-low latency on subsequent requests.

Standard Transformations (Available on All Tiers)

These parameters can be used by all tenants, including the free Hobby tier.

ParameterTypeDescriptionExample
wIntegerResizes the image to the specified width (1 - 5000px).?w=800
hIntegerResizes the image to the specified height (1 - 5000px).?h=600
qIntegerCompression quality percentage (1 - 100). Default is 80.?q=90
fStringOutput format (avif, webp, png, jpg). Default is avif.?f=webp
presetStringA predefined configuration identifier for pipelines.?preset=thumbnail

Advanced Compositing & Effects (Tier Gated)

Certain resource-intensive visual transformations require higher compute and are gated by your billing tier.

Attempting to use these parameters on an unsupported tier will result in a 403 Forbidden response.
ParameterTypeMinimum TierDescriptionExample
ckStringProChroma-Keying. Removes the specified hex color background.?ck=00FF00
wmStringScaleWatermarking. Overlays an asset (must exist in your namespace).?wm=logo.png
cropStringScaleAdvanced cropping coordinates/ratios.?crop=16:9

Example Usage

<!-- Automatically optimized to AVIF, width 800px, 90% quality -->
<img src="https://egn.pichaflow.com/pf_prj_your_id/product.jpg?w=800&q=90" />

<!-- Pro Tier: Removes green screen background -->
<img src="https://egn.pichaflow.com/pf_prj_your_id/product.jpg?ck=00FF00" />

<!-- Scale Tier: Overlays a watermark -->
<img src="https://egn.pichaflow.com/pf_prj_your_id/product.jpg?wm=logo.png&w=1200" />

Dashboard

Image Transformations

Learn how to transform images on the fly using PichaFlow URL parameters.