# TessaRun complete developer reference

> TessaRun is managed content and generative AI infrastructure for applications and agent-built workflows. It provides isolated workspaces, durable media assets, managed image and video generation, signed webhook events, usage attribution, and prepaid billing through an HTTP API.

Status: implementation preview

Canonical OpenAPI contract: https://tessarun.com/openapi.yaml

Human-readable documentation and API reference: https://tessarun.com/docs#api-reference

Developer portal: https://tessarun.com/developers

## Purpose

Use TessaRun when a product needs content storage or generative image and video operations without building GPU scheduling, provider adapters, job durability, metering, and asset delivery.

Customers consume the hosted API. Customers do not receive or run the TessaRun infrastructure repository. TessaRun does not need to know the customer's downstream users.

## Base URL and authentication

Production base URL:

`https://api.tessarun.com/api/v1`

Send a workspace API key as a Bearer token:

`Authorization: Bearer tr_live_...`

Keep API keys server-side. Do not expose keys in browser JavaScript, mobile binaries, public source code, or logs sent to third parties.

Every API key belongs to exactly one workspace. Authentication resolves that workspace and its parent infrastructure account. Request parameters cannot override either boundary. A key from one workspace cannot read an identifier owned by another workspace.

## Resource model

Infrastructure account:

- Represents the direct TessaRun customer.
- Owns the shared prepaid balance.
- Contains one or more workspaces.

Workspace:

- Is a customer-controlled isolated tenant.
- Owns API keys, assets, generations, webhook endpoints, and attributed usage.
- Is a logical grouping and reporting boundary, not a prescribed development or production environment.

Tenant:

- Is an optional customer-defined string inside a workspace.
- Can represent the customer's own user, team, project, or customer.
- Is indexed for filtering and returned for attribution.
- Is not an identity principal, authorization boundary, separate balance, or TessaRun account.

Metadata:

- Is an optional customer-defined JSON object stored and returned unchanged.
- Can contain identifiers such as `user_id`, `project_id`, and `org_id` plus other customer context.
- Is not indexed or trusted for authorization, deduplication, scheduling, or billing.

## First generation

List the available models before creating a generation:

```bash
curl https://api.tessarun.com/api/v1/models \
  -H "Authorization: Bearer $TESSARUN_API_KEY"
```

Choose a model whose `availability` is `preview`. The initial text-to-image model is `krea-2` (`KREA 2`). Read `GET /models/krea-2` for its complete parameter schema.

Then create the generation:

```bash
curl https://api.tessarun.com/api/v1/generations \
  -H "Authorization: Bearer $TESSARUN_API_KEY" \
  -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"
    }
  }'
```

A newly accepted operation returns HTTP 202. Every request creates a new generation.

## Generation lifecycle

1. TessaRun authenticates the workspace API key.
2. TessaRun validates the logical model and parameters and calculates a fixed price.
3. TessaRun atomically creates the operation, debits the parent account balance, and records `generation.accepted`.
4. TessaRun durably dispatches the operation to managed compute.
5. Provider callbacks advance the operation through submitted and running states.
6. Success creates a durable output asset and a successful usage record.
7. Failure records the infrastructure error and fully refunds the customer charge.
8. TessaRun sends each recorded lifecycle event to matching active webhook endpoints.

Generation statuses:

- `pending`
- `submitted`
- `running`
- `succeeded` (terminal)
- `failed` (terminal)

Customer-requested cancellation is not supported in the v1 preview. Accepted work runs until it succeeds or fails.

## Executable models

### KREA 2

Model ID: `krea-2`

Media type: image

Capability: text to image

Important parameters:

- `prompt`: required string, maximum 20,000 encoded bytes.
- `aspect_ratio`: one of `1:1`, `4:3`, `3:2`, `16:9`, `21:9`, `3:4`, `2:3`, `9:16`, `4:5`, or `5:4`. Default: `4:5`.
- `resolution`: `1k`, `1.5k`, or `2k`. Default: `1.5k`.
- `steps`: `8`, `10`, `12`, `14`, or `16`. Default: `8`.
- `schedule`: `linear` or `beta`. Default: `beta`.
- `seed`: optional integer.
- `character_lora`: optional object.
- `loras`: array. Default: empty.

### TessaRun H3

Model ID: `minimax-h3`

Media type: video

Capabilities: text to video and image to video with joint audio

Important parameters:

- `prompt`: required string, maximum 20,000 encoded bytes.
- `image`: optional starting media input containing exactly one `asset_id` or HTTPS `url`.
- `end_image`: optional ending media input containing exactly one `asset_id` or HTTPS `url`.
- `aspect_ratio`: supported image ratio. Default: `9:16`.
- `duration`: integer from 5 through 14 seconds. Default: 5.
- `draft`: boolean. Default: false.
- `interpolate`: boolean. Default: true.
- `num_inference_steps`: `10`, `30`, or `50`. Default: `30`.
- `seed`: optional integer.

Call `GET /models` or `GET /models/{model_id}` for the current catalog and parameter contracts. An availability value of `preview` identifies models that currently accept generation requests.

## Endpoint reference

### Models

`GET /models`

List discoverable logical models.

`GET /models/{model_id}`

Get one model's stable ID, media type, capabilities, providers, availability, and parameters.

### Generations

`GET /generations`

List recent generations in the authenticated workspace. Accepts optional `?tenant=<value>` filtering.

`POST /generations`

Validate, price, debit, and submit managed generation work.

Media inputs accept exactly one of these shapes:

```json
{"image": {"asset_id": "018f350c-2685-7c0b-9baa-4a0d0d2466ad"}}
```

```json
{"image": {"url": "https://uploads.example.com/opening.png?signature=..."}}
```

An Asset must be ready and belong to the authenticated workspace. HTTPS URL inputs remain temporary and do not create Assets.

`GET /generations/{generation_id}`

Read current state, validated parameters, fixed price, customer attribution, terminal error, and output assets.

### Assets

`GET /assets`

List workspace assets. Accepts optional `?tenant=<value>` filtering.

`POST /assets`

Create a pending asset and a short-lived direct upload request.

Example request:

```json
{
  "media_kind": "image",
  "filename": "reference.png",
  "mime_type": "image/png",
  "tenant": "customer-42",
  "metadata": {
    "project_id": "project-7",
    "role": "reference"
  }
}
```

Upload the bytes using the returned presigned R2 request. Then call the completion endpoint.

`GET /assets/{asset_id}`

Read one workspace asset.

`POST /assets/{asset_id}/complete`

Verify the uploaded object, record authoritative size and content type, and mark the asset ready.

`GET /assets/{asset_id}/download`

Return a short-lived direct download URL for a ready asset.

### Webhooks

`GET /webhook_event_types`

List the event types available for webhook subscriptions.

`GET /webhook_endpoints`

List the authenticated workspace's registered webhook destinations.

`POST /webhook_endpoints`

Register a public HTTPS destination. Select specific types with `event_types`; an empty array selects every available type. The create response is the only normal response that includes the initial `whsec_` signing secret.

```json
{
  "url": "https://app.example.com/webhooks/tessarun",
  "event_types": ["generation.succeeded", "generation.failed"]
}
```

`GET /webhook_endpoints/{webhook_endpoint_id}`

Read one webhook endpoint without its signing secret.

`PATCH /webhook_endpoints/{webhook_endpoint_id}`

Change the URL, description, event selection, or `active`/`disabled` status.

`DELETE /webhook_endpoints/{webhook_endpoint_id}`

Delete one webhook endpoint.

`POST /webhook_endpoints/{webhook_endpoint_id}/rotate_secret`

Replace the signing secret. The response includes the new secret.

Initial event types:

- `generation.accepted`
- `generation.submitted`
- `generation.running`
- `generation.succeeded`
- `generation.failed`

TessaRun sends the selected events as HTTPS POST requests. Deliveries include `webhook-id`, `webhook-timestamp`, and `webhook-signature`. Verify `v1,<base64-hmac>` using HMAC-SHA256 over `webhook-id.webhook-timestamp.raw_body` and the decoded `whsec_` secret. Reject timestamps more than five minutes from the current time and compare the signature in constant time against the exact raw body before parsing JSON.

Destinations must use HTTPS and resolve to public addresses. TessaRun rejects private, loopback, link-local, and credential-bearing URLs, repeats destination checks at delivery, and does not follow redirects. Return a 2xx response after accepting a delivery. After a terminal event, `GET /generations/{generation_id}` returns the full output Assets or failure details.

### Usage and balance

`GET /usage`

Return the parent account's current prepaid balance and successful usage records attributed to the workspace. Usage records carry optional tenant and metadata values.

`GET /balance_transactions`

Return immutable ledger entries attributed to the workspace, including generation charges and failure refunds. Account-level funding entries and sibling workspace transactions are excluded.

## Pricing and failure policy

Generation pricing is fixed from the chosen model parameters and debited when the generation is accepted.

If a generation fails, the customer receives a full refund even when TessaRun incurred provider or execution cost.

The API returns HTTP 402 when the shared parent account balance is insufficient or the account is past due.

Storage charges will use the same prepaid balance. Storage policy includes a grace period, blocked content access after the grace period, and eventual deletion after an additional disclosed retention period.

## Limits

- `tenant`: maximum 255 characters.
- Generation prompt: maximum 20,000 encoded bytes.
- Resource metadata: maximum 32,000 encoded bytes.

## Errors

Stable public errors never expose database or provider internals.

Representative envelope:

```json
{
  "error": {
    "type": "validation_error",
    "details": [{
      "field": "prompt",
      "message": "must be at most 20000 encoded bytes"
    }]
  }
}
```

Important status codes:

- 200: successful read.
- 201: asset or webhook endpoint created.
- 202: generation accepted.
- 401: missing or invalid workspace API key.
- 402: insufficient prepaid funds or past-due account.
- 404: resource does not exist inside the authenticated workspace.
- 422: request validation failed.

## Integration invariants

- A workspace API key cannot read or mutate another workspace.
- The accepted generation price does not change after submission.
- A terminal generation failure refunds the complete generation charge.
- Tenant and metadata values are returned for attribution but do not grant authority.
- Media upload and download URLs are short-lived.
- Webhook deliveries are signed per endpoint and sent only for that endpoint's selected event types.
- Customer-requested cancellation is not supported in the v1 preview.

## Deliberate v1 exclusions

- Customer-requested cancellation.
- Postpaid monthly invoicing.
- Billing the customer's downstream users.
- Customer-provided models or compute.
- Arbitrary ComfyUI graph hosting.
- Hosted Apps and agent runtime.
- Batch discounts.

## Canonical links

- Developer portal: https://tessarun.com/developers
- Human-readable API reference: https://tessarun.com/docs#api-reference
- OpenAPI 3.1: https://tessarun.com/openapi.yaml
- Concise LLM map: https://tessarun.com/llms.txt
- Account sign-up: https://tessarun.com/sign-up