Skip to integration docs

Documentation

API v1

Genaro developer documentation

Genaro is the generative-media piece of your app. You keep your own framework, host, sign-in and database. Genaro runs the models, keeps each user's library and finishes the long jobs.

You keep

Your framework, host, sign-in and database.

Genaro runs

The models, each user's library and the long jobs.

Your server routes call

https://api.genaro.ai/api/v1
Current availability: test-mode production.

The API contract and developer environment are live. Stripe accepts test payments only, and Genaro is not yet cleared for real customer funds or production media. Complete the launch gates before using this service for production workloads.

Quickstart

From API key to durable output

Get started with your agent

Set me up with Genaro: https://genaro.ai/start

Paste it into Claude, Cursor or ChatGPT. Your agent signs you up and you approve once.

Or point any MCP client at https://genaro.ai/mcp: it opens your browser to sign in, with no key to paste.

  1. 1 Paste the line
  2. 2 Approve in your browser
  3. 3 Your agent starts creating
  1. 01Create a Workspace keyConsole · shown once
  2. 02Choose a modelGET /models
  3. 03Start a generationPOST /generations · 202
  4. 04Handle completionWebhook → Generation → Asset
Run API requests from your server.

Keep the Workspace key out of browser and mobile code. Subscribe an HTTPS endpoint to generation lifecycle events, then read the completed Generation to retrieve its output Assets or error.

01 · Concepts

Accounts, Workspaces, and your users

Ownership map

One Account funds one or more isolated Workspaces.

AccountShared prepaid balance
control plane
Workspace A + key A

Owns its Generations, Assets, webhook endpoints, and usage.

Your users inside Workspace A
user_2abc123

Their Generations, Assets, and usage

user_7def456

Another user's library

Workspace B + key B

Has its own resources and users. Its key receives 404 for Workspace A IDs.

Genaro owns

Workspace isolation, durable operations and Assets, provider dispatch, signed webhook events, usage attribution, and prepaid charging.

Your application owns

Users, permissions, review and editorial decisions, customer experience, and any billing of your downstream users.

user_id, org_id, and project_id say whose a resource is.

All three are optional. Send the IDs your app already has, such as Clerk's user_… and org_…: for example "user_id": "user_2abc123", "org_id": "org_3xyz", "project_id": "project-7" on a Generation or Asset. Genaro returns them on those resources, webhook events, and usage records, and every list filters by the same names: ?user_id=user_2abc123&project_id=project-7.

metadata is yours alone: Genaro stores it and returns it unchanged, and never indexes or filters by it. The Workspace API key still controls access; none of these fields grants permission.

02 · Your users

Give every user their own library

Pass your sign-in provider's user ID with each generation and upload. Genaro keeps what each user makes together, so your app can list it back.

  1. 01Send the user's ID"user_id": "user_2abc…"
  2. 02List their libraryGET /assets?user_id=…
  3. 03See what they spentGET /usage/summary?user_id=…

Step 1 · Request

Generate for one user

POST /api/v1/generations

{
  "model": "krea-2",
  "user_id": "user_2abc123",
  "org_id": "org_3xyz",
  "project_id": "project-7",
  "params": {"prompt": "Studio portrait, soft window light"}
}

Use the IDs your sign-in provider already gives you, such as Clerk's user_… and org_…. Every Asset a generation makes carries its user_id, org_id, and project_id. Uploads (POST /assets), groups, and training take the same three fields.

Step 2 and 3 · Requests

Read it back for that user

GET /assets?user_id=user_2abc123&status=ready
GET /generations?user_id=user_2abc123
GET /usage/summary?user_id=user_2abc123
GET /generations?org_id=org_3xyz&project_id=project-7

Filters combine with AND. Lists are newest first and page with next_cursor. GET /users lists every user_id with its Asset count, and DELETE /users/{user_id} removes one user's Assets and groups when they delete their account.

Your server picks the user, never the browser.

user_id keeps users' files apart; it is not a permission. Your one key can read every user's library, so your app's server routes take the user ID from the signed-in session and only then call Genaro. See Request fields for the limits on these fields and metadata.

03 · First generation

Create your first generation

Create and fund an Account, create a Workspace key, then run these requests from your server. The plaintext key is shown once.

  1. 01List modelsGET /models
  2. 02Choose an executable modelGET /models/:model_id
  3. 03Create a generationPOST /generations

Step 1 · Request

List available models

curl · list models
curl https://api.genaro.ai/api/v1/models \
  -H "Authorization: Bearer gn_live_REPLACE_ME"

Step 1 · 200 OK · selected fields

Choose an available model

{
  "object": "list",
  "data": [{
    "id": "krea-2",
    "name": "KREA 2",
    "type": "image",
    "capabilities": ["text_to_image"],
    "availability": "preview",
    "parameters": {
      "prompt": {"type": "string", "required": true},
      "aspect_ratio": {"type": "enum", "default": "4:5"},
      "resolution": {"type": "enum", "default": "2k"}
    }
  }]
}
Use an executable model: availability available or preview.

The model list can include models that are visible but do not accept generation requests yet. Read GET /models/krea-2 for the complete parameter schema before building the request body.

Step 3 · Request

Create a generation request

curl · create generation
curl https://api.genaro.ai/api/v1/generations \
  -H "Authorization: Bearer gn_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2",
    "user_id": "user_2abc123",
    "org_id": "org_3xyz",
    "project_id": "project-7",
    "params": {
      "prompt": "A copper robot in a daylight studio",
      "aspect_ratio": "4:5",
      "resolution": "2k"
    },
    "metadata": {"scene_id": "opening_title"}
  }'

Immediate response · 202 Accepted · selected fields

Handle the 202 response

{
  "id": "0190d9b8-7d31-7c0b-9aaa-4a0d0d2466ad",
  "object": "generation",
  "status": "pending",
  "model": "krea-2",
  "user_id": "user_2abc123",
  "org_id": "org_3xyz",
  "project_id": "project-7",
  "metadata": {"scene_id": "opening_title"},
  "price": {"value": "0.065400", "currency": "usd"},
  "assets": [],
  "error": null,
  "accepted_at": "2026-08-17T18:42:05Z",
  "created_at": "2026-08-17T18:42:05Z"
}

Terminal response · 200 OK · selected fields

Download the output Asset

{
  "id": "0190d9b8-7d31-7c0b-9aaa-4a0d0d2466ad",
  "object": "generation",
  "status": "succeeded",
  "model": "krea-2",
  "price": {"value": "0.065400", "currency": "usd"},
  "assets": [{
    "id": "0190d9c1-46ba-78be-8123-6d40462e26bd",
    "object": "asset",
    "status": "ready",
    "media_kind": "image",
    "mime_type": "image/png"
  }],
  "error": null,
  "finished_at": "2026-08-17T18:42:41Z"
}

Status check

GET /generations/0190d9b8-...

After a completion webhook, read the generation to retrieve its full Asset or error details.

Download

GET /assets/0190d9c1-.../download

The response contains a short-lived download URL. Treat that URL as a secret capability.

04 · Assets

Media inputs and Asset uploads

A URL is read for one generation. An Asset is a durable, Workspace-scoped media resource that can be reused and downloaded later.

Use asset_id when

  • The input should remain durable.
  • You will reuse or audit it.
  • You want Workspace ownership checked.
"image": {"asset_id": "0190..."}

Use url when

  • The HTTPS source is temporary.
  • It stays readable until dispatch begins.
  • You do not need a Genaro Asset for the input.
"image": {"url": "https://..."}

Direct upload sequence

  1. 01 · CreatePOST /assets

    Receive the pending Asset and short-lived PUT URL.

  2. 02 · UploadPUT signed_url

    Upload bytes directly to object storage.

  3. 03 · CompletePOST /assets/:id/complete

    Genaro verifies the object and marks it ready.

  4. 04 · Useasset_id or /download

    Reference it in work or request a short-lived GET URL.

Ready means usable.

A generation input must reference a ready Asset of the correct media kind in the same Workspace. A temporary URL input does not create an Asset. Keep upload and download URLs out of logs because possession grants temporary access.

Workflows

Apps

An App is a durable workflow you write in TypeScript with @genaro/apps-sdk and publish to a Workspace. A run's generations and text model calls go through the same pipelines as the API key that started it; the run suspends while a generation or a person's review is pending and resumes when it is ready.

The Apps guide explains how to write, test, publish and run one, with every ctx action and review type. Its plain-text twin is written for coding agents.

Scopes

Publishing needs content:write; starting runs and answering review steps needs generate; reading Apps, runs, traces and reviews needs read. The key's model allow-list and spend cap govern every generation and text model call a run makes, and revoking the key stops the run.

Operation REST (/api/v1) MCP tool
List and get Apps GET /apps GET /apps/{app_id} genaro_list_appsgenaro_get_app
Publish from TypeScript source or a bundle POST /apps genaro_publish_app
Archive an App POST /apps/{app_id}/archive genaro_archive_app
Start a run POST /apps/{app_id}/runs genaro_create_app_run
List and get runs GET /app_runs GET /app_runs/{app_run_id} genaro_list_app_runsgenaro_get_app_run
Read a run's execution trace GET /app_runs/{app_run_id}/trace genaro_get_app_run_trace
List and get review steps GET /app_reviews GET /app_reviews/{app_review_id} genaro_list_app_reviewsgenaro_get_app_review
Answer a review step POST /app_reviews/{app_review_id}/resolve genaro_resolve_app_review

Classification

Judgments

POST /judgments asks TypeSafe's Jev typed questions about text and images: is the face visible, which reference does this take match, where is the logo. Jev never writes text; it returns probabilities your code thresholds. Models are the type: judgment entries of GET /models, pinned versions such as jev-1.14.0.

Type Asks Answers
noul A yes/no question; optional criteria define true and false. noul, the probability of yes
choice One option of criteria, an object of option names to descriptions or example images. choice, confidence, probabilities
score A level on criteria, an ordered array of 1 to 10 levels. score, confidence, legend, probabilities
box Where one thing is in an image (Jev 1.14). Pair it with a noul: there is no "not found". box: top, bottom, left, right as fractions

One yes/no question about an Asset

POST /api/v1/judgments
{
  "model": "jev-1.14.0",
  "state": {"photo": "listing"},
  "images": {"listing": {"asset_id": "6f1c..."}},
  "questions": {
    "shows_face": {
      "type": "noul",
      "instructions": "Is a person's face clearly visible in `photo`?"
    }
  }
}

→ "answers": {"shows_face": {"type": "noul", "noul": 0.97}}

A Choice whose options are example images

{
  "model": "jev-1.14.0",
  "state": {"take": "take"},
  "images": {
    "take": {"asset_id": "2b0e..."},
    "warm_ref": {"asset_id": "9d4a..."},
    "cold_ref": {"data_base64": "iVBORw0KGgo...", "format": "png"}
  },
  "questions": {
    "lighting": {
      "type": "choice",
      "instructions": "Which reference is the lighting of `take` closest to?",
      "criteria": {
        "warm_studio": "warm_ref",
        "cold_daylight": "cold_ref",
        "neither": "Matches neither reference."
      }
    }
  }
}
Images

Each key of images is your own reference, written wherever the image goes in state, instructions or criteria (never an object key); every one must be used. An image is a ready Asset (asset_id) or inline base64. Genaro rotates it upright, converts WebP, GIF and AVIF to JPEG, and resizes it so each side is 280 to 1568 pixels. Put an image several questions use in state once.

Billing

A judgment is charged the input tokens it used, images included, at the model's per-million-token price, rounded up to $0.0001; output is free. It is held at, and never charged more than, max_charge. A refused or failed judgment is not charged. Needs the generate scope; over MCP it is genaro_create_judgment.

Moderation

Safety checks

POST /safety/checks screens your own content and reports a verdict per category with evidence. Genaro never blocks anything: you decide what to do with a flagged result. The prompt check reads a generation prompt and its negative prompt with a word filter and TypeSafe's Jev; adult sexual content on its own is never flagged. The image checks nudity, sexual_act and violence read one image on Genaro's own servers, and jev_image asks TypeSafe's Jev about the same image as a fast, cheap second opinion. famous_person asks, on Genaro's own servers, whether a face belongs to one of about 93,000 famous people, and openai_moderation adds OpenAI's free moderation model on the prompt and the image. Where several sources report the same category, combined gives one verdict and shows where they disagree.

Source Categories Reports
word_filter blocked_term, minor_age, minor_abuse, minor_sexualized, minor_depicted, negative_prompt_signal; bestiality, creature, non_consent, torture alongside sexual content evidence: the matched terms and where they are in your text
jev minor, evasion; non_consent, bestiality, creature, incest, step_family, gore together with sexual content score, the probability of yes
nudity neutral, low, medium, high (Freepik's nsfw_image_detector) level and a score per level, flagged at and above flag_level
shieldstral sexual_act; gore and weapons for violence (Shieldstral-1.0-3B) score, the probability of yes, flagged at and above threshold
jev on an image nudity, gore (blood or injury) and weapons for jev_image; person and lettering (text or a watermark) as facts, never flagged. Never asked about age. score, the probability of yes, flagged at and above threshold. A preview from TypeSafe, not production-grade
arcface_r50 famous_person: every face, matched against about 93,000 famous people Per face matched and the closest person's name, Wikidata id, score and own threshold
openai openai_moderation on the prompt: sexual, minor_sexualized, harassment, hate, illicit, self_harm, violence, gore and their variants; on the image only sexual, self_harm, violence and gore Per category its input, OpenAI's score and name, flagged at OpenAI's own thresholds

Screen a prompt

POST /api/v1/safety/checks
{
  "checks": ["prompt"],
  "prompt": "h4z4l. a woman reading in a cafe",
  "negative_prompt": "blurry, child, teen",
  "options": {"prompt": {"names": ["h4z4l"]}}
}

→ "flagged": false,
  "checks": [{"check": "prompt", "categories": [
    {"category": "minor_depicted", "flagged": false,
     "source": "word_filter"},
    {"category": "minor", "flagged": false,
     "score": 0.02, "source": "jev"}, ...]}]

POST /api/v1/safety/checks
{
  "checks": ["nudity", "violence"],
  "image": {"asset_id": "5b7f0f8e-..."}
}

→ "checks": [
    {"check": "nudity", "level": "low", "flagged": false,
     "scores": {"neutral": 0.31, "low": 0.66,
                "medium": 0.12, "high": 0.02}, ...},
    {"check": "violence", "flagged": false, "categories": [
      {"category": "gore", "score": 0.01, ...},
      {"category": "weapons", "score": 0.03, ...}]}]
Options

options.prompt.names lists your LoRA trigger words and character names, read as "the woman" or "the man" so a name never looks like leetspeak or a real person. creatures: true also flags monsters and aliens in sexual content. The image checks read image as an asset_id, a url on a public HTTPS host, or data_base64. options.nudity.flag_level (default medium) and options.violence.threshold (default 0.5) set when they flag, as do options.sexual_act.threshold and options.jev_image.threshold. Video and minor are not available yet and are refused with a 422, as is any unknown check.

Famous people

famous_person reports each face's box, whether it matched, and its closest famous person: name, Wikidata id, score and that person's own threshold. It runs on Genaro's own servers, and the image never leaves Genaro. Images may be at most 10 MB and 40 megapixels. A few checks run at once; when every slot is busy, or the check is down, its result says status: "busy" (retry after error.retry_after seconds) or "unavailable", it isn't charged, and the other checks still run.

OpenAI moderation

openai_moderation is free and runs only alongside another check. It reads the prompt and the image apart, so their findings never mix; graphic violence joins gore and, on the prompt, sexual content with minors joins minor_sexualized in the combined verdict. On an image it can't spot an apparent minor. Your prompt and image are sent to OpenAI; never send known or suspected child sexual abuse material. When OpenAI is rate-limiting or down its result says status: "busy" or "unavailable" and the other checks still run.

Combined verdict

When sources report the same category of the same input, such as nudity from Freepik and from Jev, combined.categories lists each source's own result, whether they disagree, and one verdict under combine: any (the default) flags it when any source does, majority when more than half do, all when every source does. Disagreement is the signal worth a person's look. The top-level flagged and every check's own result are unchanged.

Billing

About $0.07 per 1,000 prompt checks, often less: the Jev input tokens each check uses, never more than its max_charge. The word filter is free, and when Jev fails you get the word filter's verdict and pay nothing. Image checks are a fixed price each: about $0.04 per 1,000 images for nudity, about $0.45 per 1,000 for sexual act and violence together. jev_image is charged per Jev input token like the prompt check, about $0.10 to $0.25 per 1,000 images depending on size. famous_person is about $0.56 per 1,000 images, and openai_moderation is free. An image check that is at capacity or down says busy or unavailable in its result, the other checks run, and it costs nothing. GET /safety/check_types lists the checks and their price. Needs the generate scope; over MCP it is genaro_create_safety_check.

05 · Platform model

How the pieces fit together

Cross-cutting Context + telemetry
  • Metadata
  • Annotations
  • Events
  • OpenTelemetry

Keep customer context, lifecycle events, and operational signals alongside the resources and work they describe.

01

Generation request

What you submit

Creative directionPromptthe result you want
Managed AIModelthe capability to run
Source mediaMedia inputsready Asset or temporary HTTPS URL
Model optionsParameterssize · duration · aspect ratio
creates

Genaro records the request, charges its quoted price, and starts one Generation.

02

Execution plane

What happened together

Trace One complete causal transaction OpenTelemetry-compatible identity
SpanGeneration Intentdesired creative outcome
Child SpanGeneration Runinputs → execution → outputs
SpanAnalysisinspect and enrich
SpanTransformderive media or Rendition
consumes · produces · observes

Trace-resource associations record which data participated in the transaction.

03

Content plane

What remains durable

Stable media identity Asset image · video · audio
Technical formRenditionoriginal · AVIF · JPEG · poster · proxy
Typed organizationGroup→ Membership → Asset
Direct causalityderived_fromsource Asset → derived Asset
ownership causal flow attachment telemetry

Execution concepts

Intent stays stable while execution changes

Trace

The complete record of one Generation. It begins when Genaro accepts the request and follows the work through completion.

Span

One timed operation inside a Trace, such as provider execution, analysis, or media transformation.

Generation Intent

The requested creative outcome: resolved prompt, media inputs, model contract, parameters, output count, and accepted price.

Generation Run

One concrete attempt through a model release and provider. A retry creates another Run without changing the original Intent.

Content concepts

Media identity is separate from file format

Asset

The durable identity of an image, video, or audio item. Storage locations and delivery formats can change without changing the Asset.

Rendition

An immutable technical form of an Asset, such as the original, an optimized AVIF, a compatibility JPEG, a poster frame, or a video proxy. A format change creates a Rendition; a semantic content change creates a new Asset.

derived_from

A direct, typed Asset-to-Asset link showing that source media contributed to derived media: a reference for each Generation input, or a kind you set yourself (edit, upscale, frame, …). Multiple inputs and outputs create multiple simple links, preserving clear ancestry.

Version

v1, v2, v3 of one thing: Assets sharing a version family, exactly one of them current. List with current_versions_only=true to see each family once.

Group + Membership

A typed, ordered or unordered collection for candidates, sequences, albums, or reference sets. Membership organizes Assets; it does not imply lineage.

Trace Resource

Associates a Trace or Span with a resource as an input, output, subject, observation, or update. Typed relationships and lineage remain distinct.

Application data · 01

Metadata

API

Keep the result connected to your application.

A generation may finish after the original request has left your server. When its webhook arrives, your application still needs to know which scene or draft requested it. Store that context with the Generation instead of reconstructing the connection later. Users, orgs, and projects have their own fields, user_id, org_id, and project_id, which lists can filter by.

A generation for one scene

{
  "project_id": "project-7",
  "metadata": {
    "scene_id": "opening_title",
    "draft": 3
  }
}

Small context, stored with the resource

Metadata is an optional JSON object that Genaro stores and returns with a resource, unchanged. Genaro never reads, indexes, or filters by it.

Good for
Scene, campaign, and draft context
Stored as
Customer-defined JSON
Returned
Unchanged with the resource
Available on
Generation and Asset requests

Application data · 02

Annotation

API

Add captions, scores, and notes.

A captioning model, a safety classifier, and a human editor may all add information to the same image. If they share one Metadata object, unrelated systems have to edit the same JSON and newer results can erase the work that came before them.

Three annotations on one Asset

[
  {
    "type": "caption",
    "data": {
      "text": "Cyclist on a wet city street"
    }
  },
  {
    "type": "safety",
    "data": {
      "classification": "safe"
    }
  },
  {
    "type": "editor_note",
    "data": {
      "text": "Use the tighter crop"
    }
  }
]

Give each result its own record.

An Annotation is a separate record attached to an Asset. One Asset can have many Annotations, so captions, scores, labels, regions, and notes from different systems and people do not overwrite one another. Each Annotation can keep its source and history without changing the Asset.

Common uses
Captions, safety results, labels, regions, and scores
Cardinality
Many Annotations can describe one Asset
Choose it when
The information may repeat, change, or need history
Create and list
/assets/{asset_id}/annotations

Integration · 03

Event

API + webhooks

Let completion come to your server.

Generation is asynchronous. Your server should not keep the request open or repeatedly check for completion. Subscribe an HTTPS endpoint to the lifecycle changes your application cares about, then react when Genaro delivers them.

generation.succeeded

{
  "object": "event",
  "type": "generation.succeeded",
  "operation_id": "0190d9b8-7d31…",
  "occurred_at": "2026-08-17T18:42:41Z"
}

A reliable record of a lifecycle change

An Event records that a specific state change happened at a specific time. Read generation Events through the API or receive selected types through signed webhooks. A succeeded Event carries the run's output Asset id and a failed Event its error, so your application can act on the Event alone.

Delivery
Signed HTTPS webhook
Current types
Accepted, submitted, running, succeeded, and failed
Use it for
Application behavior after lifecycle changes
Different from
Telemetry used to diagnose system behavior

Operations · 04

OpenTelemetry

OTLP/HTTP

See where a job spent its time.

A webhook tells your application that a Generation finished. Engineers may also want its queue time, run time, and final status in the observability system they already use.

One generation Trace

Trace: generation 0190d9…
└─ Span: genaro.generation
   ├─ generation.accepted
   ├─ generation.running
   └─ generation.failed

Send Generation traces to your observability stack.

OpenTelemetry is an industry standard for exporting operational telemetry. Register an OTLP/HTTP traces endpoint and Genaro will export a Span for each completed Generation, with its lifecycle changes recorded as Span events.

Exported signal
Generation traces
Good for
Debugging, latency, failures, and monitoring
Not product state
Telemetry may be sampled and should not drive application behavior
Configure
POST /telemetry_endpoints

Access control

API key scopes and models

One key resolves one Workspace and its parent Account. Request fields cannot override either boundary. Limit what a key can do with scopes and an optional model list.

Scope Allows
read Reads and quotes
generate Generations, chat, and agents
content:write Changes to stored content
keys Key and telemetry management; includes webhooks
webhooks Webhook endpoints and their deliveries; an agent may hold it when it asks
Model list

Set allowed_models to exact model IDs to limit generations, quotes, chat, and agent turns. null allows all models; an empty list allows none.

Legacy full access

A key created with missing or empty permissions keeps full access, so existing clients continue to work.

Bounded delegation

A key can create another key only with the same or narrower permissions and models.

A missing scope returns 403 with insufficient_scope; a forbidden model returns 403 with model_not_allowed. Create keys in the console or with POST /api/v1/api-keys.

06 · Request fields

Identifiers and request metadata

Authentication, attribution, and application metadata serve different purposes.

Value Job Scope Do not use it for
Workspace key Authentication and resource isolation One Workspace A downstream browser or mobile session
user_id, org_id, project_id Which of your users, orgs, and projects a resource belongs to; every list filters by the same names Reusable inside one Workspace Authorization, authentication, or a separate balance
metadata Your own context, stored and returned unchanged Stored on a resource Filtering, trust decisions, or billing

user_id, org_id, and project_id are strings of at most 255 characters; anything else is a 422. metadata must be a JSON object and accepts at most 32,000 encoded bytes per resource.

07 · Generations

Generation lifecycle

A generation moves forward through managed work. Your request connection may end; the generation continues until a terminal state.

1pendingAccepted, priced, debited, queued
2submittedProvider accepted dispatch
3runningProvider reports active work
succeededOutput Asset + usage record
failedError + full refund
Acceptance

Validation, pricing at the quote, operation creation, debit, and accepted event commit together.

Success

Genaro materializes output as a durable ready Asset and records successful usage.

Failure

Genaro records a stable error and fully refunds the accepted charge.

08 · Webhooks

Generation webhooks

Register an HTTPS endpoint and select the generation event types your application needs. Genaro sends each selected event to that endpoint.

Register an endpoint

Choose event types

curl https://api.genaro.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer gn_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/webhooks/genaro",
    "event_types": [
      "generation.succeeded",
      "generation.failed"
    ]
  }'

201 Created · selected fields

Store the signing secret

{
  "id": "0190da31-75b6-742d-93eb-4907d32d2c15",
  "object": "webhook_endpoint",
  "url": "https://app.example.com/webhooks/genaro",
  "event_types": [
    "generation.failed",
    "generation.succeeded"
  ],
  "status": "active",
  "signing_secret": "whsec_..."
}

The signing secret is returned only when the endpoint is created or its secret is rotated. An empty event_types array subscribes the endpoint to every available type.

Verify every delivery

  1. 1. Read the exact raw request body.
  2. 2. Reject webhook-timestamp values more than five minutes from the current time.
  3. 3. Compare the HMAC signature in constant time before decoding JSON.
  4. 4. Return a 2xx response after accepting the event.

Signed HTTP POST

Webhook delivery

{
  "id": "0190da43-ddc4-79f5-b78e-e011866a78cc",
  "object": "event",
  "type": "generation.succeeded",
  "operation_id": "0190d9b8-7d31-7c0b-9aaa-4a0d0d2466ad",
  "user_id": "user_2abc123",
  "org_id": "org_3xyz",
  "project_id": "project-7",
  "data": {
    "id": "0190d9b8-7d31-7c0b-9aaa-4a0d0d2466ad",
    "run_id": "0190d9b8-7d4e-7a21-8c3f-5b6e0f1a9d27",
    "run_index": 0,
    "status": "succeeded",
    "model": "krea-2",
    "price": {"currency": "usd", "value": "0.065400"},
    "output": {
      "asset_id": "0190d9c1-2f0a-7b44-9e8d-3c1a6b7e5f90",
      "content_type": "image/png",
      "size_bytes": 1843204,
      "width": null,
      "height": null,
      "duration": null
    }
  },
  "metadata": {"scene_id": "opening_title"},
  "occurred_at": "2026-08-17T18:42:41Z"
}
Signature input

Deliveries include webhook-id, webhook-timestamp, and webhook-signature. The signed content is webhook-id.webhook-timestamp.raw_body using HMAC-SHA256 and the endpoint secret.

Terminal event data

generation.succeeded adds data.output with the run's output Asset: asset_id, content_type, size_bytes, width, height, and duration (seconds). Dimensions and duration are measured after the Asset is stored, so they are often null in the event; read the Asset when you need them. output is null for a run whose result is data rather than an Asset. generation.failed adds data.error with the run's code and message, as the Generation returns them. Use GET /generations/:generation_id only for what the event does not carry.

Agents

MCP

Genaro's tools are an MCP server at https://api.genaro.ai/mcp. It speaks standard Streamable HTTP (protocol versions 2025-06-18 and 2025-03-26) with JSON responses, and uses the same Workspace API key as the REST API.

shell · Claude Code
claude mcp add --transport http genaro https://api.genaro.ai/mcp \
  --header "Authorization: Bearer $GENARO_API_KEY"

Send only Authorization, Content-Type: application/json, and an Accept that allows JSON. tools/list, genaro_list_models, and genaro_quote_generation are free; genaro_create_generation bills like POST /generations. The key's scopes and model list apply to every tool call.

Apps have their own tools: genaro_publish_app, genaro_create_app_run, genaro_get_app_run, genaro_resolve_app_review and the rest listed under Apps. Starting a run is free; its generations and text model calls bill as the run reaches them.

Or sign in instead of pasting a key

Clients that support MCP sign-in (Claude Code, the Claude apps, Cursor, ChatGPT) connect with no key: add https://genaro.ai/mcp (Claude Code: claude mcp add --transport http genaro https://genaro.ai/mcp). The client opens your browser, you sign in and approve once, choosing the workspace and a monthly spending cap, and the agent appears under Connected agents, where you can revoke it. Genaro is the OAuth 2.1 authorization server: authorization code with PKCE, clients identified by a Client ID Metadata Document or dynamic client registration.

Connect an agent with one line

Paste Set me up with Genaro: https://genaro.ai/start into your agent. It reads https://genaro.ai/auth.md, registers with your email, and shows you a link and a 6-digit code. You approve once in the browser, choosing the workspace and a monthly spending cap; the agent then collects a workspace API key and adds this MCP server itself. You can revoke it under Connected agents in the console. The flow follows WorkOS's auth.md protocol (v0.6.0, service_auth only), with discovery at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server; every 401 from the API and MCP carries WWW-Authenticate: Bearer resource_metadata="…".

09 · Billing

Pricing, balances, and refunds

The parent Account holds the prepaid balance shared by its Workspaces. A Workspace key can read only that Workspace’s resources, successful usage, and attributed ledger entries.

When accepted

Quoted price is charged, at most

Genaro charges the price returned with the accepted generation response. That is the most the generation costs: it can settle below it at completion, never above.

If the generation succeeds

Charge remains or settles lower; usage is recorded

When a length held at its maximum is measured, or the provider that served the run reports a lower cost, the difference is refunded as a separate refund ledger entry. Successful work appears in /usage with its user_id, org_id, and project_id.

If the generation fails

Charge is fully refunded

Failed work does not create a successful usage record.

GET /usage

Returns the current shared Account prepaid balance plus successful usage attributed to this Workspace.

Money values are exact USD decimal strings with six fractional digits.

GET /balance_transactions

Returns immutable charges and refunds attributed to this Workspace. Account funding and sibling Workspace entries stay excluded.

10 · Errors

Error handling

Error bodies use error.type, an optional human message, and optional details. Provider and database internals do not cross the public boundary.

{
  "error": {
    "type": "validation_error",
    "details": [{
      "field": "prompt",
      "message": "must be at most 20000 encoded bytes"
    }]
  }
}
Status Typical meaning Your action
401 Missing, invalid, expired, or revoked key Stop and repair credentials.
403 account_blocked: the Account is blocked for non-payment. Every route refuses the key; the error carries a resume_url. Add funds at resume_url, then retry.
402 Insufficient funds, or account_past_due: reads and downloads still work but new generations and agent turns are refused Add funds, then submit the work.
404 Unknown ID or ID owned by another Workspace Check the ID and authenticated Workspace.
422 Validation, model, or media-input error Correct the request before submitting a new generation.

Use the HTTP status and error.type for program logic. Use the OpenAPI document for the wire-level response schema.

11 · Operations

Best practices

Follow these practices when storing credentials, handling webhook events and media, and reconciling usage.

  • ✓

    Keep Workspace keys on the server and out of client bundles, logs, and transcripts.

  • ✓

    Separate environments with separate Workspaces when independent isolation is useful.

  • ✓

    Persist every returned generation ID beside your own job or resource record.

  • ✓

    Subscribe to generation.succeeded and generation.failed, then handle both.

  • ✓

    Verify webhook timestamps and signatures against the exact raw request body.

  • ✓

    Use ready Assets for durable or reusable media; keep signed URLs out of logs.

  • ✓

    Authorize your users in your application; user_id only records which user a resource belongs to.

  • ✓

    Handle 401, 402, 404, and 422 responses explicitly.

  • ✓

    Monitor prepaid balance and reconcile usage and ledger entries by Workspace.

  • ✓

    Pin integration tests to OpenAPI and the exact endpoint behavior you depend on.

12 · Reference

API endpoints

This endpoint index belongs to the integration path explained above. The OpenAPI 3.1 document remains the canonical source for request and response schemas.

Models

GET
/models

List discoverable logical models.

GET
/models/{model_id}

Read one model and its current parameter schema.

Generations

GET
/generations

List recent Workspace generations.

POST
/generations

Validate, price, debit, and submit managed work.

GET
/generations/{generation_id}

Read current state, price, errors, and output Assets.

Assets

GET
/assets

List durable Workspace Assets.

POST
/assets

Create a pending Asset and direct upload request.

GET
/assets/{asset_id}

Read one Asset in the authenticated Workspace.

POST
/assets/{asset_id}/complete

Verify the stored object and mark the Asset ready.

GET
/assets/{asset_id}/download

Create short-lived direct download URLs, up to 24 hours with expires_in.

Groups

GET
/groups

List typed Workspace Asset groups.

POST
/groups

Create a Group with an optional initial Asset order.

GET
/groups/{group_id}

Read one Group and its ordered Assets.

PATCH
/groups/{group_id}

Change the type, name, or metadata without changing membership.

PUT
/groups/{group_id}/assets

Atomically replace the complete ordered Asset list.

DELETE
/groups/{group_id}

Delete the Group while retaining every Asset.

Users

GET
/users

List every user_id in the Workspace with its Asset count.

GET
/users/{user_id}

Read one user, including the progress of a deletion.

DELETE
/users/{user_id}

Delete the user's Assets, groups, and stored objects in the background.

Apps

GET
/apps

List the Workspace's active Apps.

POST
/apps

Publish an App from TypeScript source or a built bundle as a new version.

GET
/apps/{app_id}

Read one App by id or slug.

POST
/apps/{app_id}/archive

Archive an App; runs in progress finish.

POST
/apps/{app_id}/runs

Start a run with input the App's schema accepts.

App runs and reviews

GET
/app_runs

List App runs, newest first.

GET
/app_runs/{app_run_id}

Read a run's status, steps, logs, result, and pending review.

GET
/app_runs/{app_run_id}/trace

Read the run's execution trace as a tree of spans.

GET
/app_reviews

List review steps runs are waiting on or have finished.

GET
/app_reviews/{app_review_id}

Read one review step.

POST
/app_reviews/{app_review_id}/resolve

Answer a pending review step; the run resumes.

Agents

GET
/agents

List Workspace Agents.

POST
/agents

Create a conversational Agent definition.

GET
/agents/{agent_id}

Read one Agent by UUID or key.

PATCH
/agents/{agent_id}

Update any Agent field except the immutable key.

DELETE
/agents/{agent_id}

Archive the Agent; existing Conversations stay readable.

GET
/agent-tools

List builtin tools an Agent can be granted.

Conversations

GET
/conversations

List Conversations, optionally filtered by Agent.

POST
/conversations

Create a Conversation bound to one Agent.

GET
/conversations/{conversation_id}

Read one Conversation and its pending tool calls.

DELETE
/conversations/{conversation_id}

Archive the Conversation; messages stay readable.

GET
/conversations/{conversation_id}/messages

List the message transcript in ascending order.

POST
/conversations/{conversation_id}/messages

Send a user message and run one agent turn, optionally streamed.

POST
/conversations/{conversation_id}/tool-results

Answer pending client tool calls and resume the paused turn.

Events, webhooks, usage, and balance

GET
/webhook_event_types

List the available webhook event types.

GET
/webhook_endpoints

List Workspace webhook endpoints.

POST
/webhook_endpoints

Register an HTTPS destination and receive its signing secret.

GET
/webhook_endpoints/{webhook_endpoint_id}

Read one Workspace webhook endpoint.

PATCH
/webhook_endpoints/{webhook_endpoint_id}

Change the URL, event selection, description, or status.

DELETE
/webhook_endpoints/{webhook_endpoint_id}

Delete a webhook endpoint.

POST
/webhook_endpoints/{webhook_endpoint_id}/rotate_secret

Replace the endpoint signing secret.

GET
/events

List durable generation lifecycle events.

GET
/events/{event_id}

Read one lifecycle event.

GET
/usage

Read successful usage and the shared prepaid balance.

GET
/balance_transactions

List Workspace-attributed charges and refunds.

Annotations

GET
/assets/{asset_id}/annotations

List the independent results attached to an Asset.

POST
/assets/{asset_id}/annotations

Attach a caption, score, label, region, or note.

GET
/annotations/{annotation_id}

Read one Annotation.

OpenTelemetry

GET
/telemetry_endpoints

List Workspace OTLP/HTTP trace destinations.

POST
/telemetry_endpoints

Register an OTLP/HTTP traces endpoint.

GET
/telemetry_endpoints/{telemetry_endpoint_id}

Read one telemetry destination without secret header values.

PATCH
/telemetry_endpoints/{telemetry_endpoint_id}

Change its destination, headers, service name, or status.

DELETE
/telemetry_endpoints/{telemetry_endpoint_id}

Delete a telemetry destination.