---
title: Core concepts
description: The main objects and lifecycle behind the Sume developer platform.
---

This page is the **job and admission** map — catalog, jobs, artifacts, usage.
For a product map of Agents, Formats, Models, and clients, see
[Sume basics](/the-basics).

Sume generation workflows are built from a small set of public objects:
catalog items, media inputs, jobs, artifacts, usage entries, and dashboard
resources.

## Platform domains

| Domain / URL | Role |
|---|---|
| `www.sume.com/dashboard` | Dashboard home and operator surfaces. |
| `www.sume.com/dashboard/api-keys` | API key management. |
| `www.sume.com/dashboard/jobs` | Job inspection. |
| `www.sume.com/dashboard/usage` | Usage and balance summary. |
| `www.sume.com/dashboard/subscription` | Billing & subscription / credit top-ups. |
| `www.sume.com/playground` | Avatar playground. |
| `api.sume.com` | Public Developer API (`/v1`) and OpenAPI (`/reference/json`). |
| `media.sume.com` | First-party generated media artifacts. |

## Catalog

`GET /v1/catalog` is the best starting point for programmatic discovery. It
lists available capabilities, model ids, endpoint paths, runtime readiness, and
pricing metadata.

## Jobs

Generation requests create durable jobs. A job tracks request metadata, status,
public provider model, result, public error, events, and webhook delivery state.

Supported statuses:

```text
queued -> processing -> completed
queued -> processing -> failed
queued -> canceled
```

## Generation lifecycle

```text
client submit
  -> Sume validates API key and request
  -> optional usage reservation
  -> provider-backed execution
  -> artifact mirroring to media.sume.com
  -> usage capture or refund
  -> terminal webhook delivery when configured
  -> result available from /v1/jobs/:id/result
```

If a client disconnects or times out locally, keep the job id and recover with
the jobs API instead of submitting duplicate paid work.

## Artifacts

Completed jobs can include public artifacts under `https://media.sume.com`.
Sume-owned artifact URLs are the public contract. Raw provider URLs are not.

## Media inputs

Launch generation requests accept public HTTPS media URLs in schema-defined
fields such as `input.image_url`, `product_image`, `scene.image_url`, and
`video_url` (face-swap / captions). You do not need a separate asset upload
step for normal integrations. Generated outputs are returned as Sume-hosted
artifacts under `media.sume.com`. See [Media inputs](/workflows/asset-library).

## Usage

Provider-backed generation can reserve estimated USD-denominated usage, capture
actual cost on success, and refund on failure or cancellation before capture.
Use `/v1/balance` and `/v1/usage` to inspect current balance and ledger entries.

## Dashboard

The dashboard mirrors the API surfaces for humans:

- [API keys](https://www.sume.com/dashboard/api-keys)
- [Jobs](https://www.sume.com/dashboard/jobs)
- [Usage](https://www.sume.com/dashboard/usage)
- [Billing & subscription](https://www.sume.com/dashboard/subscription)
- [Playground](https://www.sume.com/playground)