ScreenshotNeo
Sign in Get a free key

BlogEngineering

Word Definition to Image API: Generate Vocabulary Cards Programmatically

Generate customizable word-definition graphics with an API. Learn the request format, fields, output options, bulk workflows, and production troubleshooting.

By the ScreenshotNeo team1 October 20267 min read

Use a word-definition image template API when you need consistent vocabulary cards without drawing each card by hand. The documented Orshot workflow uses the word-definition-image template and a JSON request to https://api.orshot.com/v1/generate/images. You provide the word, meaning, typography, colors, and dimensions, then request an output such as PNG, JPG, PDF, or MP4.

This guide shows the complete request, every documented customization field, runnable examples in cURL, Python, and Node.js, bulk-generation patterns, failure handling, and production considerations.

1. What a word-definition image API does

A word-definition image API renders a word and its meaning into a designed graphic. Instead of assembling text, fonts, colors, and layout in your own image-processing code, you submit structured data to a named template.

The documented template is word-definition-image. A typical render contains:

  • The word, such as Opacarophile
  • A definition, such as (n.) A person who loves sunsets.
  • Configurable font sizes and font family
  • Separate colors for the background, word, and meaning
  • A pixel-based width and height

2. Request format

Send a POST request with JSON and a bearer token:

POST https://api.orshot.com/v1/generate/images
Content-Type: application/json
Authorization: Bearer <ORSHOT_API_KEY>

The request body identifies the template, selects the response type, and supplies modifications:

{
  "templateId": "word-definition-image",
  "responseType": "png",
  "modifications": {
    "word": "Opacarophile",
    "meaning": "(n.) A person who loves sunsets.",
    "wordFontSize": 96,
    "meaningFontSize": 36,
    "fontFamily": "Inter",
    "backgroundColor": "#101828",
    "wordColor": "#FFFFFF",
    "meaningColor": "#D0D5DD",
    "width": 1200,
    "height": 1200
  }
}

Use the exact response-type spelling accepted by your Orshot account and template configuration. The documented export options are PNG, JPG, PDF, and MP4.

3. Complete cURL example

curl -X POST "https://api.orshot.com/v1/generate/images" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ORSHOT_API_KEY" \
  -d '{
    "templateId": "word-definition-image",
    "responseType": "png",
    "modifications": {
      "word": "Opacarophile",
      "meaning": "(n.) A person who loves sunsets.",
      "wordFontSize": 96,
      "meaningFontSize": 36,
      "fontFamily": "Inter",
      "backgroundColor": "#101828",
      "wordColor": "#FFFFFF",
      "meaningColor": "#D0D5DD",
      "width": 1200,
      "height": 1200
    }
  }'

Keep the API key in an environment variable or secret manager. Do not put it in browser JavaScript or commit it to a repository.

4. Python example

import os
import requests

payload = {
    "templateId": "word-definition-image",
    "responseType": "png",
    "modifications": {
        "word": "Opacarophile",
        "meaning": "(n.) A person who loves sunsets.",
        "wordFontSize": 96,
        "meaningFontSize": 36,
        "fontFamily": "Inter",
        "backgroundColor": "#101828",
        "wordColor": "#FFFFFF",
        "meaningColor": "#D0D5DD",
        "width": 1200,
        "height": 1200,
    },
}

response = requests.post(
    "https://api.orshot.com/v1/generate/images",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['ORSHOT_API_KEY']}",
    },
    json=payload,
    timeout=90,
)
response.raise_for_status()

# The API response may contain a render URL or response metadata.
print(response.json())

5. Node.js example

const apiKey = process.env.ORSHOT_API_KEY;

const payload = {
  templateId: 'word-definition-image',
  responseType: 'png',
  modifications: {
    word: 'Opacarophile',
    meaning: '(n.) A person who loves sunsets.',
    wordFontSize: 96,
    meaningFontSize: 36,
    fontFamily: 'Inter',
    backgroundColor: '#101828',
    wordColor: '#FFFFFF',
    meaningColor: '#D0D5DD',
    width: 1200,
    height: 1200
  }
};

const response = await fetch('https://api.orshot.com/v1/generate/images', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify(payload)
});

if (!response.ok) {
  throw new Error(`Orshot request failed: ${response.status} ${await response.text()}`);
}

console.log(await response.json());

6. All documented customization fields

Field Purpose Example
word Primary vocabulary word displayed in the card Opacarophile
meaning Definition or explanatory text (n.) A person who loves sunsets.
wordFontSize Word font size in CSS pixels 96
meaningFontSize Meaning font size in CSS pixels 36
fontFamily Font used by the template Inter
backgroundColor Card background color #101828
wordColor Word text color #FFFFFF
meaningColor Definition text color #D0D5DD
width Output width in pixels 1200
height Output height in pixels 1200

Choosing dimensions

  • Use a square canvas for flashcards, social posts, and vocabulary feeds.
  • Use a wider canvas for website banners or classroom slides.
  • Use a taller canvas for mobile stories or printable study sheets.
  • Keep long meanings short enough to fit the template; reducing the font size alone can make cards difficult to read.

7. Output formats and delivery workflows

The documented template supports PNG, JPG, PDF, and MP4 export. Choose based on the destination:

Format Good fit Consideration
PNG Sharp text, transparent or graphic-heavy assets Usually larger files than JPG
JPG Web feeds and photographs or textured backgrounds Lossy compression can soften small text
PDF Printable vocabulary sheets and documents Check page dimensions before printing
MP4 Animated or video-oriented publishing workflows Confirm the template’s motion behavior before batch export

Orshot’s page also documents REST API and SDK access, spreadsheet-scale generation, Zapier, Make, n8n, Pipedream, webhooks, dynamic URLs, and signed URLs. These integrations are useful when the source list lives in a spreadsheet, CMS, or automation pipeline.

8. Generating cards in bulk

For a vocabulary list, keep the template constant and vary only the modification values. A safe batch pipeline should:

  1. Validate that every row has a word and meaning.
  2. Normalize whitespace and reject unexpectedly long values.
  3. Assign a stable identifier to each row.
  4. Submit requests with bounded concurrency.
  5. Persist the returned render reference before processing the next stage.
  6. Retry transient failures with exponential backoff.
  7. Record permanent failures with the input row and response body.
import os
import time
import requests

words = [
    {"id": "001", "word": "Ephemeral", "meaning": "(adj.) Lasting for a very short time."},
    {"id": "002", "word": "Mellifluous", "meaning": "(adj.) Pleasantly smooth and musical to hear."},
]

for item in words:
    payload = {
        "templateId": "word-definition-image",
        "responseType": "png",
        "modifications": {
            "word": item["word"],
            "meaning": item["meaning"],
            "wordFontSize": 96,
            "meaningFontSize": 36,
            "fontFamily": "Inter",
            "backgroundColor": "#101828",
            "wordColor": "#FFFFFF",
            "meaningColor": "#D0D5DD",
            "width": 1200,
            "height": 1200,
        },
    }

    for attempt in range(3):
        response = requests.post(
            "https://api.orshot.com/v1/generate/images",
            headers={"Authorization": f"Bearer {os.environ['ORSHOT_API_KEY']}"},
            json=payload,
            timeout=90,
        )
        if response.ok:
            print(item["id"], response.json())
            break
        if response.status_code not in (408, 429, 500, 502, 503, 504):
            print("permanent failure", item["id"], response.status_code, response.text)
            break
        time.sleep(2 ** attempt)
    else:
        print("retry limit reached", item["id"])

9. Common errors and fixes

Symptom Likely cause Fix
401 or 403 response Missing, malformed, or unauthorized API key Send Authorization: Bearer ..., verify the key, and keep it server-side.
Template not found Incorrect template identifier Use exactly word-definition-image.
Validation error Malformed JSON or unsupported modification value Check commas, field names, numeric dimensions, and color syntax.
Text is clipped Meaning is too long for the selected dimensions and font sizes Shorten the definition, enlarge the canvas, or reduce the relevant font size.
Wrong output type Response type does not match the consumer Request PNG, JPG, PDF, or MP4 explicitly and handle the returned metadata.
Intermittent timeout Transient service or network delay Use a generous client timeout, retry only transient statuses, and cap concurrency.
Duplicate cards Retries were not idempotently recorded Store a stable input ID and response reference before retrying downstream work.

10. Performance, reliability, and cost planning

  • Reuse one template: Keeping layout decisions in the template reduces per-request payload size and makes batches consistent.
  • Control concurrency: A queue with a small worker pool is safer than launching thousands of requests simultaneously.
  • Retry carefully: Retry timeouts and 5xx responses; do not blindly retry authentication or validation errors.
  • Cache by content: Hash the word, meaning, format, dimensions, and style fields. Reuse an existing render when that hash already exists in your system.
  • Track usage: Record request IDs, input IDs, response types, and failures so a large run can resume.
  • Pricing: The researched template page documents the workflow and export options but does not publish pricing or usage limits. Confirm current plan details before committing to a large batch.

11. When to use a screenshot API instead

A word-definition API is the direct choice when you want a designed card from structured text. A screenshot API is useful when the source is already rendered as a webpage, dashboard, lesson, or custom HTML/CSS layout.

12. Or skip the browser setup

If your definition cards are rendered in a webpage or HTML template and you need image or PDF output, ScreenshotNeo provides a single screenshot request. Its API can capture full pages or selected elements, apply custom CSS and JavaScript, wait for selectors or network idle, and return PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for the complete parameter list.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. An MCP server lets Claude, Cursor, and other MCP clients take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

13. FAQ

Can I generate definition cards without building an image renderer?

Yes. Submit the template ID and modification values to the documented REST endpoint, then consume the returned render response.

Which fields control typography?

wordFontSize, meaningFontSize, and fontFamily control the documented typography settings.

Can the same workflow create printable files?

Yes. PDF is one of the documented output formats; set dimensions and content for the intended page or card size.

Is there a physical product involved?

No. This is a hosted digital rendering workflow accessed through an API, SDKs, and automation integrations.

Can I connect a spreadsheet or automation tool?

The documented integrations include spreadsheet-scale generation, Zapier, Make, n8n, Pipedream, webhooks, dynamic URLs, and signed URLs.

Keep reading