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.
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/v1How 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.
a1b2c3d4-e5f6-7890-abcd-ef1234567890Error 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 |
{
"status": false,
"type": "error",
"title": "Not Found",
"message": "Template not found",
"http_code": 404
}Simple URL
Generate images using a simple GET request. Pass template variables as query parameters. Perfect for embedding directly in HTML or sharing links.
https://snapshark.io/api/v1/images/:templateIdQuery 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 |
| model | string | optional | AI 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
https://snapshark.io/api/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890?title=Hello&subtitle=Worldhttps://snapshark.io/api/v1/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890?title=Hello&output=imageHTML Embed
<!-- 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
{
"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"
}
}API Request
Generate images with a POST request. Ideal for server-side integration and complex variable data.
https://snapshark.io/api/v1/imagesRequest 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:
{
"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
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
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 URLDownload Image Directly
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.pngTemplate Variables
Variables are based on layer names in your template. Each editable layer becomes an API variable.
Variable Types
For text layers. Use text property in POST, or pass value directly in GET query.
?title=Hello%20World{ "name": "title", "text": "Hello World" }For image layers. Provide an image URL to replace the placeholder.
?avatar.src=https://example.com/photo.jpg{ "name": "avatar", "src": "https://..." }For shape fill colors. Provide a hex color code.
?background.fill=%23FF5733{ "name": "background", "color": "#FF5733" }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.
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.
https://snapshark.io/api/v1/contactsAuthentication
All Contacts endpoints require an API token (create one under Settings → Security & Tokens). Pass it any of three ways:
| Parameter | Type | Required | Description |
|---|---|---|---|
| X-API-Token | header | optional | X-API-Token: YOUR_API_TOKEN |
| Authorization | header | optional | Authorization: Bearer YOUR_API_TOKEN |
| token | query | optional | ?token=YOUR_API_TOKEN (for no-code tools like Zapier, Make, Google Sheets) |
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.
https://snapshark.io/api/v1/contactsRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| fullName | string | required | Full name (or send firstName + lastName instead) |
| title | string | optional | Job title |
| company | string | optional | Company name |
| string | optional | Email address — also used for deduplication | |
| phone | string | optional | Phone number (digits and + ( ) - . separators) |
| linkedinUrl | URL | optional | LinkedIn profile URL — also used for deduplication |
| photoUrl | URL | optional | Portrait photo — copied to CDN automatically |
| location / country / headline / notes | string | optional | Extra profile fields |
| customFields | object | optional | Any extra key → value pairs, e.g. {"event": "DevSummit 2026"} |
| tags | string[] | optional | Tag names — created automatically if they don’t exist |
| upsert | boolean | optional | true: update the existing contact when email or LinkedIn matches, instead of creating a duplicate |
cURL Example
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
}'{
"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.
https://snapshark.io/api/v1/contacts| Parameter | Type | Required | Description |
|---|---|---|---|
| q | string | optional | Search in name, job title, company and email |
| tag | string | optional | Filter by tag name, e.g. ?tag=Speaker |
| source | string | optional | manual | excel | api | linkedin |
| page / limit | number | optional | Pagination — limit max 100, default 50 |
Single Contact
https://snapshark.io/api/v1/contacts/:idhttps://snapshark.io/api/v1/contacts/:idExample
curl 'https://snapshark.io/api/v1/contacts?tag=Speaker&limit=20' \
-H 'X-API-Token: YOUR_API_TOKEN'{
"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:
https://snapshark.io/api/v1/contacts/columns{
"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.
https://snapshark.io/api/v1/contacts/render| Parameter | Type | Required | Description |
|---|---|---|---|
| contactIds | string[] | required | Up to 500 contact IDs |
| templateIds | string[] | required | Up to 5 template IDs — one job is created per template |
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"]
}'{
"success": true,
"data": {
"jobs": [
{
"bulkImportId": "job-uuid",
"templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"totalRows": 1
}
],
"warnings": []
}
}Poll Job Progress
https://snapshark.io/api/v1/contacts/render-jobs?ids=job-uuidEach 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
https://snapshark.io/api/v1/contacts/:id/renders{
"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.
https://api.snapshark.io/mcpAuthentication
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.
https://api.snapshark.io/mcpFor 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
- Settings → Connectors → add the URL above (auth: OAuth)
- Sign in on the SnapShark page that opens and click Allow access
- 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. |
Example Prompt
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