Documentation · Managed GenAI infrastructure

Quickstart

From API key to durable output

01Create a Workspace keyConsole · shown once
02Choose a modelGET /models
03Start a generationPOST /generations · 202
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.

Make the first request ↓ Configure webhooks ↓

01 · Concepts

Accounts, Workspaces, and tenants

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.

Optional tenants inside Workspace A

customer-42

Its Generations, Assets, and usage

project-red

A different resource group

Workspace B + key B

Has its own resources and optional tenants. 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.

A tenant groups related resources inside one Workspace.

A tenant is an optional identifier chosen by your application. It usually represents one of your customers, users, teams, or projects. For example, send "tenant": "customer-42" on that customer’s Generations and Assets. Genaro returns the tenant on those resources, webhook events, and usage records, and list endpoints can filter by it.

Use tenant to group many resources. Use metadata to attach your own user, project, organization, or other identifiers to a resource. The Workspace API key still controls access; neither tenant nor metadata grants permission.

02 · 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, fixes the 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 Asset-to-Asset link showing that source media contributed to derived media. Multiple inputs and outputs create multiple simple links, preserving clear ancestry.

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 project, user, or scene requested it. Store those identifiers with the Generation instead of reconstructing the connection later.

A generation for project_7

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

Small context, stored with the resource

Metadata is an optional JSON object that Genaro stores and returns with a resource. It keeps your application’s identifiers and context alongside a Generation or Asset.

Good for: Project, user, campaign, and scene IDs
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. After a completion Event arrives, your application can read the Generation once for its output Assets or failure details.

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

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.

01List modelsGET /models
02Choose a preview modelGET /models/:model_id
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": "1.5k"}
    }
  }]
}

Use a model whose availability is 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

server → Genaro

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",
    "tenant": "customer-42",
    "params": {
      "prompt": "A copper robot in a daylight studio",
      "aspect_ratio": "4:5",
      "resolution": "1.5k"
    },
    "metadata": {
      "user_id": "user-42",
      "project_id": "project-7",
      "org_id": "org-3"
    }
  }'

Immediate response · 202 Accepted · selected fields

Handle the 202 response

{
  "id": "0190d9b8-7d31-7c0b-9aaa-4a0d0d2466ad",
  "object": "generation",
  "status": "pending",
  "model": "krea-2",
  "tenant": "customer-42",
  "metadata": {
    "user_id": "user-42",
    "project_id": "project-7",
    "org_id": "org-3"
  },
  "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 · 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
`tenant`	Groups many resources for one customer, user, team, or project	Reusable inside one Workspace	Authorization, authentication, or a separate balance
`metadata`	Your identifiers and other structured context, returned unchanged	Stored on a resource	Indexed lookup, trust decisions, or billing

tenant accepts at most 255 characters. metadata must be a JSON object and accepts at most 32,000 encoded bytes per resource.

05 · 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, price fixation, 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.

06 · 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

01 · CreatePOST /assets
Receive the pending Asset and short-lived PUT URL.
02 · UploadPUT signed_url
Upload bytes directly to object storage.
03 · CompletePOST /assets/:id/complete
Genaro verifies the object and marks it ready.
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.

07 · 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. Read the exact raw request body.
2. Reject webhook-timestamp values more than five minutes from the current time.
3. Compare the HMAC signature in constant time before decoding JSON.
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",
  "tenant": "customer-42",
  "data": {
    "id": "0190d9b8-7d31-7c0b-9aaa-4a0d0d2466ad",
    "status": "succeeded",
    "model": "krea-2",
    "price": "0.065400"
  },
  "metadata": {
    "user_id": "user-42",
    "project_id": "project-7",
    "org_id": "org-3"
  },
  "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. After a terminal event, use GET /generations/:generation_id once to retrieve the complete output Assets or failure details.

08 · 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

Fixed price is charged

Genaro charges the price returned with the accepted generation response.

If the generation succeeds

Charge remains; usage is recorded

Successful work appears in /usage with tenant and metadata attribution.

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.

09 · 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.

10 · 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 a short-lived direct download URL.

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.

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.

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 downstream users in your application; use tenant only for attribution.
✓
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.

Look upAPI referenceMethods, paths, and resources ↑ Machine contractOpenAPI 3.1Canonical wire schema ↗ For coding agentsFull contextLLM-readable contract ↗

Genaro developer documentation

From API key to durable output

Accounts, Workspaces, and tenants

How the pieces fit together

Intent stays stable while execution changes

Media identity is separate from file format

Keep the result connected to your application.

Small context, stored with the resource

Add captions, scores, and notes.

Give each result its own record.

Let completion come to your server.

A reliable record of a lifecycle change

See where a job spent its time.

Send Generation traces to your observability stack.

Create your first generation

List available models

Choose an available model

Create a generation request

Handle the 202 response

Download the output Asset

Identifiers and request metadata

Generation lifecycle

Media inputs and Asset uploads

Generation webhooks

Choose event types

Store the signing secret

Webhook delivery

Pricing, balances, and refunds

Fixed price is charged

Charge remains; usage is recorded

Charge is fully refunded

Error handling

API endpoints

Models

Generations

Assets

Groups

Agents

Conversations

Events, webhooks, usage, and balance

Annotations

OpenTelemetry

Best practices