Documentation

Welcome to the Poststack documentation. Here you will find everything you need to integrate our powerful media optimization features into your applications.

1. Uploading an Image

To upload an image, you need to send a multipart/form-data POST request to our media API endpoint. The request must include your project-specific Secret Key in the Authorization header.

The form data should contain a single field named data, which holds the image file.

JavaScript Fetch Example

// Make sure to replace with your actual Project ID and Secret API Key
const projectId = 'YOUR_PROJECT_ID';
const secretKey = 'sk_live_...';
const imageFile = event.target.files[0]; // Assuming this comes from a file input

const formData = new FormData();
formData.append('data', imageFile);

fetch(`https://api-euw1.poststack.dev/projects/${projectId}/media`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${secretKey}`
  },
  body: formData
})
.then(response => {
  if (!response.ok) {
    throw new Error('Upload failed');
  }
  return response.json();
})
.then(data => {
  console.log('Upload successful:', data);
  
  // Extract the mediaId and save it to your database
  const { mediaId } = data;
  
  // Example: saveToYourDatabase({ mediaId, ... });
})
.catch(error => {
  console.error('Error uploading image:', error);
});

Upon a successful upload, the API will return a JSON object with metadata about the processed image. The most important field is the mediaId, which you must save in your database. This ID is the unique reference to your media asset within Poststack.

Example API Response

{
  "filename": "mountains-test.jpg",
  "size_bytes": 158183,
  "mime_type": "image/jpeg",
  "width": 1920,
  "height": 1440,
  "status": "PROCESSING",
  "mediaId": "686069b5becd123a193138bb"
}

2. Using Images

Once you have uploaded an image and saved its mediaId, you can easily display optimized versions in your Next.js application using our dedicated component.

Installation

npm install @poststack/next

Environment Variables

To use the component, you must configure three environment variables in your .env.local file. These variables provide the component with the necessary credentials to fetch images from your project.

NEXT_PUBLIC_POSTSTACK_PROJECT=YOUR_PROJECT_ID
NEXT_PUBLIC_POSTSTACK_PK=pk_live_...
NEXT_PUBLIC_POSTSTACK_ENDPOINT=https://api-euw1.poststack.dev

Component Usage

Import the PoststackImage component and use it in your application, passing the mediaId you saved earlier.

import { PoststackImage } from '@poststack/next';

function MyComponent({ mediaId, projectId }) {
  return (
    <PoststackImage
      responsive
      projectId={projectId}
      mediaId={mediaId}
      maxWidth={600}
      proportions="4:3"
      alt="A descriptive alt text for your image"
    />
  );
}