hermosodocs

SDKs

Typed clients for the Hermoso API in TypeScript and Python. Generate image and video ads, publish and schedule posts to your own channels, read your analytics, and call any of the 1584 tools from your own backend.

LanguagePackageInstall
TypeScript, Node 18+@hermoso/sdknpm install @hermoso/sdk
Python 3.11+hermosopip install "git+https://github.com/hermoso-ai/hermoso-sdks#subdirectory=python"

Both are generated from the API's OpenAPI document, so every /v1 operation is a typed function and every request and response a typed model. A small hand-written layer adds the four things a generator does not: a client that reads your key, a paginator, a job waiter and a one-line tool call. Source: github.com/hermoso-ai/hermoso-sdks.

Your key

Create an API key in the app on the API, MCP & CLI tab, under Terminal & API keys, and set it as HERMOSO_API_KEY. Both clients read it from there when you do not pass one. Server-side only: a key carries full account authority, so it never belongs in a browser. New accounts start free with no card.

An account with several brands: pass brand (an id from listBrands / list_brands) when you create the client, and every call acts on that brand.

Generate an ad

runTool (in Python, run_tool(…)) reaches every tool through POST /v1/tools/{name}, the same set an agent gets over MCP. With wait: 0 a render answers at once with a job; wait on it, then read url.

// TypeScript
import { createHermosoClient, runTool, waitForJob } from '@hermoso/sdk';

const hermoso = createHermosoClient(); // reads HERMOSO_API_KEY
const started = await runTool('generate_image', {
  prompt: 'Summer launch ad for our cold brew: the can on a sunlit cafe table, headline "Cold. Brewed. Yours."',
  job: 'static_ad',
  aspectRatio: '4:5',
}, { client: hermoso, wait: 0 });
const job = await waitForJob((started as { job_id: string }).job_id, { client: hermoso });
console.log(job.url);
# Python
from hermoso import create_client, run_tool, wait_for_job

client = create_client()  # reads HERMOSO_API_KEY
started = run_tool("generate_image", {
    "prompt": 'Summer launch ad for our cold brew: the can on a sunlit cafe table, headline "Cold. Brewed. Yours."',
    "job": "static_ad",
    "aspectRatio": "4:5",
}, client=client, wait=0)
job = wait_for_job(started.job_id, client=client)
print(job.url)

The ad lands on your saved brand. For a video ad, plan_ad then render_ad; GET /v1/tools/{name} describes any tool's arguments. Generation costs credits, and POST /v1/generations/quote prices a render for free first. Polling a job is free; calling the tool again would start a second render.

Schedule a post

// TypeScript
import { createPost } from '@hermoso/sdk';

const { data: post, error } = await createPost({
  client: hermoso,
  body: { channels: ['instagram', 'facebook'], caption: 'Cold. Brewed. Yours.', media: [job.url!], scheduled_at: '2026-12-01T15:00:00Z' },
  headers: { 'Idempotency-Key': crypto.randomUUID() },
});
# Python
import uuid
from hermoso.api.posts import create_post
from hermoso.models import PostCreate

post = create_post.sync(client=client, body=PostCreate.from_dict({
    "channels": ["instagram", "facebook"], "caption": "Cold. Brewed. Yours.",
    "media": [job.url], "scheduled_at": "2026-12-01T15:00:00Z",
}), idempotency_key=str(uuid.uuid4()))

listChannels says which channels this brand has connected. Omit scheduled_at to publish now. Publishing is free. Posts covers carousels, per-channel captions and the queue.

Read analytics

// TypeScript
import { getBestTime, listPosts, paginate } from '@hermoso/sdk';

const { data: best } = await getBestTime({ client: hermoso, query: { channel: 'instagram', timezone: 'America/New_York' } });
for await (const post of paginate(listPosts, { client: hermoso, query: { status: 'published' } })) console.log(post.id);
# Python
from hermoso import paginate
from hermoso.api.analytics import get_best_time
from hermoso.api.posts import list_posts

best = get_best_time.sync(client=client, channel="instagram", timezone="America/New_York")
for post in paginate(list_posts, client=client, status="published"):
    print(post.id)

Also under analytics: posting frequency, content decay, follower history and inbox stats. Per-post and ad-platform numbers (post_performance, meta_insights, google_ads_report and the rest) are tools, so they go through runTool.

The helpers

TypeScriptPythonWhat it does
createHermosoClient()create_client()A client authenticated with your key, optionally pinned to one brand.
paginate(fn, options)paginate(module, client=…)Every item of a cursor-paginated list, following next_cursor to the last page.
waitForJob(id)wait_for_job(id)Polls a render until it is done or error.
runTool(name, args)run_tool(name, args)Calls any tool and raises on an error answer.

Every generated operation returns the typed error body rather than throwing; the helpers throw HermosoError. In Python each operation also has asyncio(…).

Versions and the spec

The SDKs are generated from app.hermoso.ai/openapi.json, which is itself rendered from the table the API's router is mounted from. When the API gains an endpoint or a field, both SDKs are regenerated and released together under one version number; a release cannot go out while they trail the spec. The /v1 contract only grows, so upgrading never breaks working code. Prefer another language? Point any OpenAPI generator at the same document.