API Reference

Snapshark API

Generate dynamic images from your templates using simple HTTP requests. Each template has a unique ID that you use to generate images with custom text and images.

RESTJSONPNG / WebP / PDF

Introduction

Generate dynamic images from your templates using simple HTTP requests. Each template has a unique ID that you use to generate images with custom text and images.

Base URL

https://snapshark.io/api/v1

PNG, JPG

Output formats

CDN

Fast global delivery

Image Retention

Generated images are automatically deleted after 30 days. Make sure to download or cache images you need to keep.

How It Works

Every template you create in the editor gets a unique UUID. Use this ID to generate images via the API with your custom data.

Create a Template

Design your template in the editor with text and image layers.

Get Template ID

Copy the UUID from the Generate page or template settings.

Call the API

Make a GET or POST request with your variable values.

Example Template ID (UUID)

a1b2c3d4-e5f6-7890-abcd-ef1234567890

Error Handling

All API responses follow a consistent format. Errors include a descriptive message.

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
404	Not Found - Template doesn't exist
500	Server Error

Response404 Error

{
  "status": false,
  "type": "error",
  "title": "Not Found",
  "message": "Template not found",
  "http_code": 404
}

GET

Simple URL

Generate images using a simple GET request. Pass template variables as query parameters. Perfect for embedding directly in HTML or sharing links.

GEThttps://snapshark.io/api/v1/images/:templateId

Query Parameters

Parameter	Type	Required	Description
:templateId	UUID	required	Your template ID (in URL path)
title	string	optional	Any text variable name from your template
image.src	URL	optional	Any image variable with .src suffix
output	string	optional	"json" (default) or "image" for binary

Examples

Get JSON response with image URL

https://snapshark.io/api/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890?title=Hello&subtitle=World

Get image binary directly (for img src)

https://snapshark.io/api/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890?title=Hello&output=image

HTML Embed

html

<!-- Embed generated image directly in HTML -->
<img src="https://snapshark.io/api/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890?title=My%20Title&output=image" alt="Generated" />

<!-- Dynamic OG Image for social sharing -->
<meta property="og:image" content="https://snapshark.io/api/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890?title=Article%20Title&output=image" />

JSON Response

Response200 OK

{
  "status": true,
  "type": "success",
  "title": "OK",
  "message": "Image generated successfully",
  "http_code": 200,
  "href": ".../generated/2024/01/abc123.png",
  "data": {
    "id": "abc123-uuid",
    "image_url": ".../generated/2024/01/abc123.png",
    "width": 1200,
    "height": 630,
    "format": "png",
    "file_size": 125000,
    "render_time_ms": 450,
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

POST

API Request

Generate images with a POST request. Ideal for server-side integration and complex variable data.

POSThttps://snapshark.io/api/v1/images

Request Body

Parameter	Type	Required	Description
template	UUID	required	Your template ID
data	array	required	Array of variable modifications
output	string	optional	"json" (default) or "image" for binary

Data Array Format

Each item in the data array specifies a variable to modify:

json

{
  "template": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": [
    { "name": "title", "text": "Hello World" },
    { "name": "subtitle", "text": "Welcome to Snapshark" },
    { "name": "avatar", "src": "https://example.com/photo.jpg" },
    { "name": "background", "color": "#FF5733" }
  ],
  "output": "json"
}

cURL Example

cURLbash

curl -X POST 'https://snapshark.io/api/v1/images' \
  -H 'Content-Type: application/json' \
  -d '{
    "template": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "data": [
      { "name": "title", "text": "Hello World" },
      { "name": "subtitle", "text": "Generated via API" }
    ],
    "output": "json"
  }'

Node.js Example

Node.jsjavascript

const response = await fetch('https://snapshark.io/api/v1/images', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    template: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    data: [
      { name: 'title', text: 'Hello World' },
      { name: 'avatar', src: 'https://example.com/photo.jpg' }
    ],
    output: 'json'
  })
});

const result = await response.json();
console.log(result.href); // Image URL

Download Image Directly

cURL - Save to filebash

curl -X POST 'https://snapshark.io/api/v1/images' \
  -H 'Content-Type: application/json' \
  -d '{
    "template": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "data": [{ "name": "title", "text": "Hello" }],
    "output": "image"
  }' \
  --output generated-image.png

Template Variables

Variables are based on layer names in your template. Each editable layer becomes an API variable.

Variable Types

Text Variables

For text layers. Use text property in POST, or pass value directly in GET query.

GET

?title=Hello%20World

POST

{ "name": "title", "text": "Hello World" }

Image Variables

For image layers. Provide an image URL to replace the placeholder.

GET

?avatar.src=https://example.com/photo.jpg

POST

{ "name": "avatar", "src": "https://..." }

Color Variables

For shape fill colors. Provide a hex color code.

GET

?background.fill=%23FF5733

POST

{ "name": "background", "color": "#FF5733" }

Finding Variable Names

Go to your template's Generate page to see all available variables and their names. The page shows live API URLs as you edit values.

Output Options

Control the API response format using the output parameter.

Value	Response	Use Case
json	JSON with image URL and metadata	API integrations, store URL
image	Binary image data (PNG/JPG)	Direct embed, download

Output Formats

Images are generated in PNG format by default. JPG is also supported for templates configured with JPG export.

MCP · AI Assistants

Connect ChatGPT or Claude to SnapShark via MCP (Model Context Protocol). Your assistant can turn any design image into a layered template, design templates from a text description, and generate personalized images — using its own vision, right from the chat.

POSThttps://api.snapshark.io/mcp

Authentication

Just add the server URL — SnapShark implements the standard MCP OAuth flow, so ChatGPT/Claude will open a SnapShark page where you sign in and approve the connection. No keys to copy. Revoke access anytime under Settings → Security & Tokens.

Server URLurl

https://api.snapshark.io/mcp

For clients without OAuth support you can instead pass an API token — as an Authorization: Bearer <token> header or embedded in the URL: https://api.snapshark.io/mcp?token=YOUR_API_TOKEN

Setup

ChatGPT

Settings → Connectors → add the URL above (auth: OAuth)
Sign in on the SnapShark page that opens and click Allow access

Claude

Settings → Connectors → Add custom connector
Paste the URL, click Connect and approve on the SnapShark page

Manage or revoke connections at snapshark.io/app/settings/security — full setup guide on the in-app page /app/settings/mcp.

Available Tools

Tool	Description
create_template	Build a template from a structured layer spec — returns a rendered preview the model compares against the target.
update_template	Full-spec correction loop: the model fixes positions, fonts and colors until the preview matches.
get_template_spec	Reads an existing template back as an editable spec, so an assistant can change a template it did not build.
render_preview	Credit-free test render with sample variables (e.g. a very long name).
list_templates	List your templates so the assistant can work with existing designs.
get_template_variables	List the dynamic variables a template accepts at generation time.
generate_image	Final render — consumes credits, returns the CDN URL (plus a verification code for certificate templates).
request_upload_link / check_upload	One-time browser upload page for images that only exist as chat files.

How it works

All AI reasoning happens in the connected assistant on your own subscription — SnapShark only validates, saves and renders. Preview images are returned inline so the model iterates until the result matches your design.

Example Prompt

In ChatGPT or Claudetext

Here's a photo of our certificate — make it a SnapShark template where name and date are variables, then generate one for Ada Lovelace.

Ready to generate?

Grab your API key from account security settings — or start free with 100 credits and design your first template.

Get your API key Start for free

Need help? Contact us at support@snapshark.io

View Pricing