Output retention and pricing

llms.txt Ask agent

# Output retention and pricing

Source: https://docs.originalpictures.com/api/retention-pricing/
Full index for AI agents: https://docs.originalpictures.com/llms.txt

This guide describes the additive retention/pricing implementation introduced in the September 2026 submission-readiness branch. Availability depends on the deployed API version. These endpoints do not activate a subscription or charge a payment method.

## Token retention

Each API key can select `1h`, `24h`, `72h`, or `retain` for **future published outputs**. The clock starts at validated publication, not upload or queue admission. A job snapshots its policy when admitted; editing or rotating a key cannot rewrite already admitted jobs.

New accounts default to 72 hours. Migration preserves existing accounts' default behavior and existing unversioned keys as `legacy`. Omitting `retention_mode` when issuing a key uses that account's default. The console's new-key form explicitly shows 72 hours before creation; choose the required policy in the review step. Rotation inherits the outgoing key's policy without changing its secret or updating another token's lineage.

| Operation                                          | Required API-key scope |
| -------------------------------------------------- | ---------------------- |
| `GET /v1/api-keys/{api_key_id}/retention`          | `governance:read`      |
| `PUT /v1/api-keys/{api_key_id}/retention`          | `governance:write`     |
| `POST /v1/api-keys` with optional `retention_mode` | `governance:write`     |

Read before updating. Send the returned version as `expected_version`:

```json
{
  "retention_mode": "72h",
  "expected_version": 1
}
```

The response identifies the key, the current version and mode, `effective_for: "future_job_admissions"`, and `clock_starts_at: "validated_publication"`. An unversioned key reports version `0` and mode `legacy`; `legacy` is not a selectable public mode. A stale version returns HTTP 409. Delegated keys cannot widen their own retention ceiling or the tenant's governance ceiling, and cannot change a broader-scope target.

### What expiry does—and does not do

Customer download URLs and preview capabilities cannot extend past the published output's deadline. New issuance and preview redemption are refused after that cutoff. The existing governance worker schedules the exact expired output version for deletion, with legal-hold checks, retry/fencing, revocation and deletion evidence. A failed storage deletion is not recorded as a successful purge.

This implementation does **not** reinterpret historical objects or delete their creation-time retention pins. It does not yet apply token deadlines to independently retained source uploads, processing scratch objects, preview derivatives, backups or provenance evidence. Their separate governance policies still apply. Consequently, output expiry is not a promise that every copy of source media has been erased. Storage authorization and production exact-version deletion must be qualified before claiming an operational purge guarantee.

The privacy model is private server processing: encrypted transport/storage and authorized processing can coexist with customer-only media UI. It is not end-to-end encryption, and a retention setting alone does not establish regulatory compliance.

## Versioned price catalog

`GET /v1/billing/pricing` returns the USD catalog and its immutable version. `POST /v1/billing/quotes` estimates processing from caller-supplied dimensions, duration and frame rate. Both require `billing:read`. A quote is not a promise that a format or runtime is qualified.

Both answer with the catalog your account is enrolled on: the same version a job you submit now snapshots at admission. An account that has not been enrolled on a catalog is not charged for processing; it is shown the current catalog, which `activation: "requires_explicit_tenant_enrollment"` marks as not yet applying to it.

The initial catalog is `op.pricing.2026-09-15.v1`:

| Item                        | USD rate                                                                      |
| --------------------------- | ----------------------------------------------------------------------------- |
| Sign                        | $0.01 per successful asset operation                                          |
| Image watermark             | $0.02 up to 1 MP; $0.03 up to 2 MP; $0.04 up to 4 MP; $0.05 up to 8 MP        |
| Larger image watermark      | Add $0.01 for each started 4 MP above 8 MP                                    |
| Audio watermark             | $0.002 per second; $0.02 minimum                                              |
| Video watermark             | $0.02 per second up to 1280×720; $0.04 up to 1920×1080; $0.08 up to 3840×2160 |
| Video frame-rate multiplier | `max(1, fps / 30)`; portrait and landscape use the same tier                  |
| Logical storage             | $0.15 per decimal GB-month, using 730 hours                                   |
| Egress                      | $0.12 per decimal GB                                                          |
| Optional asset overage      | $0.01 per asset; disabled                                                     |

Larger-than-4K video and unqualified watermark content families have no implicit fallback rate. Missing or invalid facts return HTTP 422 instead of an invented estimate. Decimal seconds are supported; no whole-minute rounding is applied. Ledger precision is six decimal USD places; invoice aggregation is a separate concern.

The current catalog is `op.pricing.2026-09-27.v1`. It has every rate above and one more line:
a job whose [`fingerprint_algorithms`](/api/sign/#choose-fingerprints) differs from its media
type's default set pays a `fingerprint` line at the watermark rate for the same media (image
megapixel bands, audio per second with its minimum, video per second times the frame-rate
multiplier). Keeping the default costs nothing extra. `op.pricing.2026-09-15.v1` is unchanged and
never charges the line; an account keeps the version it is enrolled on until it is moved.

Monthly subscription catalog: $99/10,000 assets, $299/50,000, $599/150,000, and $999/500,000. These fees include **no signing or watermark credits**. Existing negotiated commercial terms are not automatically migrated.

Example quote request:

```json
{
  "operation": "watermark_then_sign",
  "media_family": "audio",
  "duration_seconds": "1.25"
}
```

This estimates $0.02 audio watermarking plus $0.01 signing. The response labels it `estimate_only`, identifies its price version, and excludes subscription, storage, egress and tax. Final processing ledger amounts use trusted server inspection facts and the version snapshotted at admission.

## Charges and counting

`GET /v1/billing/charges` requires `billing:read` and lists tenant-owned processing ledger records. Pagination uses `limit` (1–100, default 50) and the response's `next_before` UUID as the next request's `before` value. No API-key credential, filename, media URL or storage key appears in a charge.

Processing charges are recorded only when a job successfully publishes under an explicitly enrolled price version. Publication retries cannot duplicate an action charge. Failed, cancelled or not-yet-published work has no processing charge. A distinct source asset UUID counts once per tenant service period after its first successful processing operation; separate uploads have separate UUIDs. Watermark-and-sign counts one asset and two processing actions. Reprocessing the same source may create new action charges, but not a second asset count in that period.

Logical storage pricing is defined over customer-retained plaintext bytes and time, excluding encryption overhead, replicas, internal evidence, thumbnails and processing scratch space. This slice exposes the rate calculation but does not yet settle storage/egress invoices or automatically bill subscription/overage fees. Payment-provider charge creation remains disabled here.

`GET /v1/usage` is unchanged. Its `cost_estimate` and `pricing_version` remain null-only. Do not reinterpret operational meters as money or fill those fields from the new quote endpoint.

New rates require a new immutable catalog version and explicit tenant enrollment. Changing policy affects future admissions only; it is not permission to replace a live customer's API key or historical commercial terms.

This guide describes the additive retention/pricing implementation introduced in the September 2026 submission-readiness branch. Availability depends on the deployed API version. These endpoints do not activate a subscription or charge a payment method.

Token retention

Each API key can select 1h, 24h, 72h, or retain for future published outputs. The clock starts at validated publication, not upload or queue admission. A job snapshots its policy when admitted; editing or rotating a key cannot rewrite already admitted jobs.

New accounts default to 72 hours. Migration preserves existing accounts’ default behavior and existing unversioned keys as legacy. Omitting retention_mode when issuing a key uses that account’s default. The console’s new-key form explicitly shows 72 hours before creation; choose the required policy in the review step. Rotation inherits the outgoing key’s policy without changing its secret or updating another token’s lineage.

Operation	Required API-key scope
`GET /v1/api-keys/{api_key_id}/retention`	`governance:read`
`PUT /v1/api-keys/{api_key_id}/retention`	`governance:write`
`POST /v1/api-keys` with optional `retention_mode`	`governance:write`

Read before updating. Send the returned version as expected_version:

{
  "retention_mode": "72h",
  "expected_version": 1
}

The response identifies the key, the current version and mode, effective_for: "future_job_admissions", and clock_starts_at: "validated_publication". An unversioned key reports version 0 and mode legacy; legacy is not a selectable public mode. A stale version returns HTTP 409. Delegated keys cannot widen their own retention ceiling or the tenant’s governance ceiling, and cannot change a broader-scope target.

What expiry does—and does not do

Customer download URLs and preview capabilities cannot extend past the published output’s deadline. New issuance and preview redemption are refused after that cutoff. The existing governance worker schedules the exact expired output version for deletion, with legal-hold checks, retry/fencing, revocation and deletion evidence. A failed storage deletion is not recorded as a successful purge.

This implementation does not reinterpret historical objects or delete their creation-time retention pins. It does not yet apply token deadlines to independently retained source uploads, processing scratch objects, preview derivatives, backups or provenance evidence. Their separate governance policies still apply. Consequently, output expiry is not a promise that every copy of source media has been erased. Storage authorization and production exact-version deletion must be qualified before claiming an operational purge guarantee.

The privacy model is private server processing: encrypted transport/storage and authorized processing can coexist with customer-only media UI. It is not end-to-end encryption, and a retention setting alone does not establish regulatory compliance.

Versioned price catalog

GET /v1/billing/pricing returns the USD catalog and its immutable version. POST /v1/billing/quotes estimates processing from caller-supplied dimensions, duration and frame rate. Both require billing:read. A quote is not a promise that a format or runtime is qualified.

Both answer with the catalog your account is enrolled on: the same version a job you submit now snapshots at admission. An account that has not been enrolled on a catalog is not charged for processing; it is shown the current catalog, which activation: "requires_explicit_tenant_enrollment" marks as not yet applying to it.

The initial catalog is op.pricing.2026-09-15.v1:

Item	USD rate
Sign	$0.01 per successful asset operation
Image watermark	$0.02 up to 1 MP; $0.03 up to 2 MP; $0.04 up to 4 MP; $0.05 up to 8 MP
Larger image watermark	Add $0.01 for each started 4 MP above 8 MP
Audio watermark	$0.002 per second; $0.02 minimum
Video watermark	$0.02 per second up to 1280×720; $0.04 up to 1920×1080; $0.08 up to 3840×2160
Video frame-rate multiplier	`max(1, fps / 30)`; portrait and landscape use the same tier
Logical storage	$0.15 per decimal GB-month, using 730 hours
Egress	$0.12 per decimal GB
Optional asset overage	$0.01 per asset; disabled

Larger-than-4K video and unqualified watermark content families have no implicit fallback rate. Missing or invalid facts return HTTP 422 instead of an invented estimate. Decimal seconds are supported; no whole-minute rounding is applied. Ledger precision is six decimal USD places; invoice aggregation is a separate concern.

The current catalog is op.pricing.2026-09-27.v1. It has every rate above and one more line: a job whose fingerprint_algorithms differs from its media type’s default set pays a fingerprint line at the watermark rate for the same media (image megapixel bands, audio per second with its minimum, video per second times the frame-rate multiplier). Keeping the default costs nothing extra. op.pricing.2026-09-15.v1 is unchanged and never charges the line; an account keeps the version it is enrolled on until it is moved.

Monthly subscription catalog: $99/10,000 assets, $299/50,000, $599/150,000, and $999/500,000. These fees include no signing or watermark credits. Existing negotiated commercial terms are not automatically migrated.

Example quote request:

{
  "operation": "watermark_then_sign",
  "media_family": "audio",
  "duration_seconds": "1.25"
}

This estimates $0.02 audio watermarking plus $0.01 signing. The response labels it estimate_only, identifies its price version, and excludes subscription, storage, egress and tax. Final processing ledger amounts use trusted server inspection facts and the version snapshotted at admission.

Charges and counting

GET /v1/billing/charges requires billing:read and lists tenant-owned processing ledger records. Pagination uses limit (1–100, default 50) and the response’s next_before UUID as the next request’s before value. No API-key credential, filename, media URL or storage key appears in a charge.

Processing charges are recorded only when a job successfully publishes under an explicitly enrolled price version. Publication retries cannot duplicate an action charge. Failed, cancelled or not-yet-published work has no processing charge. A distinct source asset UUID counts once per tenant service period after its first successful processing operation; separate uploads have separate UUIDs. Watermark-and-sign counts one asset and two processing actions. Reprocessing the same source may create new action charges, but not a second asset count in that period.

Logical storage pricing is defined over customer-retained plaintext bytes and time, excluding encryption overhead, replicas, internal evidence, thumbnails and processing scratch space. This slice exposes the rate calculation but does not yet settle storage/egress invoices or automatically bill subscription/overage fees. Payment-provider charge creation remains disabled here.

GET /v1/usage is unchanged. Its cost_estimate and pricing_version remain null-only. Do not reinterpret operational meters as money or fill those fields from the new quote endpoint.

New rates require a new immutable catalog version and explicit tenant enrollment. Changing policy affects future admissions only; it is not permission to replace a live customer’s API key or historical commercial terms.