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.

1
Create a Template
Design your template in the editor with text and image layers.
2
Get Template ID
Copy the UUID from the Generate page or template settings.
3
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 CodeDescription
200Success
400Bad Request - Invalid parameters
404Not Found - Template doesn't exist
500Server 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

ParameterTypeRequiredDescription
:templateIdUUIDrequiredYour template ID (in URL path)
titlestringoptionalAny text variable name from your template
image.srcURLoptionalAny image variable with .src suffix
outputstringoptional"json" (default) or "image" for binary
modelstringoptionalAI templates only: the image model to render with (reserved name — never a template field). Credits are charged per model; see the template’s API tab for the enabled models and prices. Unknown/disabled model → 400. Also accepted as a POST body field.

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

ParameterTypeRequiredDescription
templateUUIDrequiredYour template ID
dataarrayrequiredArray of variable modifications
outputstringoptional"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.

ValueResponseUse Case
jsonJSON with image URL and metadataAPI integrations, store URL
imageBinary 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.

Contacts CRM

Store your people — speakers, students, team members — once, then render any template for them without re-sending their data on every request. Push contacts from your backend (e.g. when someone registers for your event) and trigger speaker cards, certificates or badges in bulk.

GEThttps://snapshark.io/api/v1/contacts

Authentication

All Contacts endpoints require an API token (create one under Settings → Security & Tokens). Pass it any of three ways:

ParameterTypeRequiredDescription
X-API-TokenheaderoptionalX-API-Token: YOUR_API_TOKEN
AuthorizationheaderoptionalAuthorization: Bearer YOUR_API_TOKEN
tokenqueryoptional?token=YOUR_API_TOKEN (for no-code tools like Zapier, Make, Google Sheets)
Plan requirement
Contacts is available on Professional and Advanced plans (or as a standalone module). Requests from other plans return 403.
POST

Create Contact

Add a person to your contact store. Photos passed as URLs are copied to our CDN so they never expire. Unknown fields go into customFields and are usable as template variables.

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

Request Body

ParameterTypeRequiredDescription
fullNamestringrequiredFull name (or send firstName + lastName instead)
titlestringoptionalJob title
companystringoptionalCompany name
emailstringoptionalEmail address — also used for deduplication
phonestringoptionalPhone number (digits and + ( ) - . separators)
linkedinUrlURLoptionalLinkedIn profile URL — also used for deduplication
photoUrlURLoptionalPortrait photo — copied to CDN automatically
location / country / headline / notesstringoptionalExtra profile fields
customFieldsobjectoptionalAny extra key → value pairs, e.g. {"event": "DevSummit 2026"}
tagsstring[]optionalTag names — created automatically if they don’t exist
upsertbooleanoptionaltrue: update the existing contact when email or LinkedIn matches, instead of creating a duplicate

cURL Example

cURLbash
curl -X POST 'https://snapshark.io/api/v1/contacts' \
  -H 'X-API-Token: YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "fullName": "Jane Doe",
    "title": "Founder & CEO",
    "company": "Acme Inc.",
    "email": "jane@acme.com",
    "photoUrl": "https://example.com/jane.jpg",
    "tags": ["Speaker", "DevSummit 2026"],
    "upsert": true
  }'
Response201 OK
{
  "success": true,
  "data": {
    "id": "c1a2b3c4-uuid",
    "fullName": "Jane Doe",
    "title": "Founder & CEO",
    "company": "Acme Inc.",
    "email": "jane@acme.com",
    "photoUrl": "https://cdn.snapshark.io/contacts/.../photo.jpg",
    "tags": [
      "Speaker",
      "DevSummit 2026"
    ],
    "source": "api",
    "created": true,
    "createdAt": "2026-10-12T10:30:00.000Z"
  }
}

List & Manage

Search, read and delete contacts. All endpoints only see contacts that belong to the token's account.

GEThttps://snapshark.io/api/v1/contacts
ParameterTypeRequiredDescription
qstringoptionalSearch in name, job title, company and email
tagstringoptionalFilter by tag name, e.g. ?tag=Speaker
sourcestringoptionalmanual | excel | api | linkedin
page / limitnumberoptionalPagination — limit max 100, default 50

Single Contact

GEThttps://snapshark.io/api/v1/contacts/:id
DELETEhttps://snapshark.io/api/v1/contacts/:id

Example

cURLbash
curl 'https://snapshark.io/api/v1/contacts?tag=Speaker&limit=20' \
  -H 'X-API-Token: YOUR_API_TOKEN'
Response200 OK
{
  "success": true,
  "data": [
    {
      "id": "c1a2b3c4-uuid",
      "fullName": "Jane Doe",
      "title": "Founder & CEO",
      "company": "Acme Inc.",
      "tags": [
        "Speaker"
      ],
      "renderCount": 3
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "hasMore": false
  }
}

Custom Columns

Contacts carry a free-form customFields object. Each key maps to a typed column definition (text, number, date, url, image or select) that also appears in the Contacts table in the app. List the definitions to discover the valid keys and their types:

GEThttps://snapshark.io/api/v1/contacts/columns
Response200 OK
{
  "success": true,
  "data": [
    {
      "key": "dietary_preference",
      "label": "Dietary Preference",
      "type": "text",
      "isBuiltin": false,
      "position": 11,
      "visible": true
    }
  ]
}

How keys work

Keys you send in customFields are normalized to stable slugs ("Dietary Preference" → dietary_preference) and a text column definition is created automatically for new keys (up to 30 per account). On upsert: true, custom fields are merged into the existing contact — keys you don't send are kept, and sending an empty string deletes that key. Columns themselves are managed in the app (Contacts → Columns).

Render for Contacts

The point of the CRM: render templates for stored contacts without passing variables. Template variables are filled automatically from contact fields — full_name, job_title, company, photo layers from the contact's photo, and custom fields by name. Jobs run asynchronously; each render costs the template's normal credit price.

POSThttps://snapshark.io/api/v1/contacts/render
ParameterTypeRequiredDescription
contactIdsstring[]requiredUp to 500 contact IDs
templateIdsstring[]requiredUp to 5 template IDs — one job is created per template
cURLbash
curl -X POST 'https://snapshark.io/api/v1/contacts/render' \
  -H 'X-API-Token: YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "contactIds": ["c1a2b3c4-uuid"],
    "templateIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'
Response201 OK
{
  "success": true,
  "data": {
    "jobs": [
      {
        "bulkImportId": "job-uuid",
        "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "totalRows": 1
      }
    ],
    "warnings": []
  }
}

Poll Job Progress

GEThttps://snapshark.io/api/v1/contacts/render-jobs?ids=job-uuid

Each job reports status, progress (0–100) and per-contact items with the finished imageUrl. Poll every few seconds until the status is completed.

Render History

GEThttps://snapshark.io/api/v1/contacts/:id/renders
Response200 OK
{
  "success": true,
  "data": [
    {
      "id": "render-uuid",
      "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "imageUrl": "https://cdn.snapshark.io/generated/2026/10/abc.png",
      "createdAt": "2026-10-12T10:31:05.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 24,
    "hasMore": false
  }
}

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
  1. Settings → Connectors → add the URL above (auth: OAuth)
  2. Sign in on the SnapShark page that opens and click Allow access
Claude
  1. Settings → Connectors → Add custom connector
  2. 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

ToolDescription
create_templateBuild a template from a structured layer spec — returns a rendered preview the model compares against the target.
update_templateFull-spec correction loop: the model fixes positions, fonts and colors until the preview matches.
get_template_specReads an existing template back as an editable spec, so an assistant can change a template it did not build.
render_previewCredit-free test render with sample variables (e.g. a very long name).
list_templatesList your templates so the assistant can work with existing designs.
get_template_variablesList the dynamic variables a template accepts at generation time.
generate_imageFinal render — consumes credits, returns the CDN URL (plus a verification code for certificate templates).
request_upload_link / check_uploadOne-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.

Need help? Contact us at support@snapshark.io

View Pricing