Eve library

Hosted media lanes

Runbook

Revision 1

On this page

Isis renders on its own GPUs by default. Two hosted lanes sit beside that path — OpenRouter for images (tracker H.00–H.07) and Meshy for 3D (T.22) — and this document says how a job reaches one, what had to be read before a vendor could be offered at all, who may use them, what is recorded, and what happens when a chain mixes lanes.

Code: libs/isis/workflows/src/hosted-media/ (the OpenRouter register, the lane policy, the terms fingerprint), libs/isis/workflows/src/three-d-capabilities/hosted-lane-policy.ts and asset-lineage.ts (Meshy), libs/isis/ai-providers/src/providers/openrouter-media/ and .../meshy/ (the clients), apps/isis/generation-api/src/services/openrouter-lane/ and .../meshy-lane/ (the API boundary, the catalogs and the ledgers). Decisions: the owner's blocks of 15 September 2026 in ISIS_CHROMA_RUNPOD_MVP_TODOS_2026-09-11.md (H.00.02, T.22).

1. Nothing switches lanes on its own#

A job reaches a hosted lane only by naming one of its workflow ids — a meshy:* id for the 3D lane, an OpenRouter lane id for images. There is no router that moves work to a vendor because a GPU is busy or a price is better. The owner decision behind the Meshy lane says it plainly: it is an optional lane beside the self-hosted path, no pipeline may require it, and it does not make any self-hosted 3D capability admitted.

When a job asks for a hosted lane and the work cannot go there, the refusal names the reason and the self-hosted workflows that serve the same task. It is never quietly rendered somewhere else, and never sent with the offending field dropped. runpodOnlyReasons produces that list:

Reason Why it cannot travel
The workflow is adult_ok Every hosted model is sfw_only under its vendor's acceptable use policy.
An internal_only option is selected Internal-only weights never leave the self-hosted lane.
LoRAs They load only in the ComfyUI graph.
Control maps No equivalent in a hosted request.
Masks No equivalent in a hosted request.
A custom ComfyUI graph Runs only on the self-hosted worker.
A workflow with no hosted equivalent The register has no row for it.

An empty list means a hosted lane is possible, not that it is chosen.

2. A model is offered only after someone read the terms#

OpenRouter is the party Isis contracts with; the model vendor is not. But OpenRouter's own terms (read 2026-09-15, document last updated 2026-08-31) push the vendor's rules onto the customer anyway — 5.1 and 7(8) bind the user to "the Terms of Service for the Model or Provider you are using", and 6.1 leaves output ownership to those model terms. So the register offers a model only when someone has read the vendor's published terms, written down what they say and what they leave open, and derived a policy from that reading.

Two facts shape every row:

  • Isis is not the vendor's customer. Where a vendor's terms grant something to its customer — Google's paid-tier data promise, Black Forest Labs' training opt-out — that grant runs to OpenRouter, not to Isis. Rows say so rather than claiming the benefit.
  • A model absent from both lists is unreviewed, which means not offered. It does not mean "probably fine". A model the live catalog gains tomorrow is unreviewed by construction.

2.1 The terms register's fields#

Each OpenRouterVendorTerms record carries:

Field What it holds
vendor, url Whose terms, and where.
lastUpdated The document's own stated date, or null when it states none.
readAt When a person read it.
unitedKingdom A checkable verdict, not prose: served, not_excluded, conditional, unread, excluded, with the clause it rests on.
trainsOnInputs Likewise a verdict with its clause.
documentHash The fingerprint of the document that was read (see §2.2).
documentEvidencePath The local copy of the normalized text the hash was taken over, so --check re-hashes it offline.
findings Verbatim or near-verbatim readings, each with its clause.
openQuestions What the terms do not settle for Isis's use.

A model may be offered only on a served or not_excluded territory verdict. conditional is deliberately not enough: Google's terms serve UK users only on Paid Services, and Isis cannot see which tier OpenRouter buys, so the condition is unverifiable from here and the verdict is treated as a refusal rather than a maybe.

Each offered model then carries tasks (what it may serve), contentPolicy: sfw_only, outputDistribution (operator_internal — no row claims service yet), outputMayFeedAdultOk: false, and a one-line why.

2.2 Fingerprinting a terms document#

The register records what someone read on a date. Nothing in that record notices when the vendor edits the page afterwards — which is the whole risk, because clause 5.1/7(8) binds Isis to what the vendor's terms say now.

The hash is taken over extracted text, not response bytes, and the reason was measured on 2026-09-16 by fetching each document twice within a minute: bfl.ai/legal/terms-of-service returned byte-identical bodies; ai.google.dev returned bodies of identical length and different sha256, the whole 3,149-byte diff being per-request CSP nonce="…" attributes on <script> tags. A raw-body hash would therefore cry drift on a document nobody touched, and an alarm that fires every fetch is an alarm nobody reads. The raw hash is still recorded, with rawStable saying whether it was observed to reproduce.

This is a documented approximation and its limits are written down: the extractor is regex-based, not a parser, so a vendor serving terms only through client-side rendering would hash a near-empty string, and a re-templated page moves the text hash without a clause changing. Both fail loud — an extraction below the minimum length is refused outright, and text drift asks a person to re-read the document, which is the right answer either way. It cannot tell a reworded clause from a reformatted one; only a person reading the diff can. TERMS_TEXT_NORMALIZATION names the rules that produced a hash, so a recorded hash is recomputable years later; a normalization mismatch is refused rather than compared.

openrouter-terms-drift.ts --check re-hashes the checked-in evidence offline; --check-remote fetches the live documents.

2.3 What is offered today#

Three image models, all Black Forest Labs: flux.2-klein-4b (the cheapest reviewed model on the lane, 0.014 USD per output megapixel), flux.2-flex and flux.2-pro, each for txt2img and img-edit, all on the one BFL terms reading.

No video model at all, and the reason is terms, not capability. The cheap video vendors publish no terms this reader could reach on 2026-09-15: Alibaba's Model Studio terms answer 404 at the documented URL, ByteDance and Kuaishou were not read, Black Forest Labs' video models start at 0.17 USD/s, and Google is excluded by the owner's proof approval. So a t2v, i2v, flf2v, video-edit or video-upscale job is refused naming that blocker — not left to fall through to a model-mismatch message that hides the real reason, and openRouterModelsForTask('t2v') is empty rather than filled with a guess.

Excluded with their reasons: openai/gpt-image-2 and openai/sora-2-pro (the business terms answered HTTP 403 to a read), alibaba/wan-3.0, google/gemini-3.1-flash-image and google/veo-3.1-lite, krea/krea-2-large and minimax/hailuo-3 (both already excluded for their weights; the hosted route was not separately reviewed). Every exclusion carries a reopensWhen.

3. The exposure decisions#

Both lanes are operator-only, and each is a checked-in owner decision that no request field or environment variable can change.

  • OpenRouter (OPENROUTER_LANE_TENANT_EXPOSURE, decided 2026-09-15): "Operator only for now" — build and prove the lane operator-only; tenants need a new attestation and a per-model terms review first. It reopens on a new owner decision taken with that review and a widened Task 14.2 attestation. The owner's Task 14.2 attestation covers the Isis generation API, the operator tenant and operator-owned non-personal material — and nothing in the register claims an output may be sold or handed to a tenant.
  • Meshy (MESHY_TENANT_EXPOSURE_DECISION, decided 2026-09-15): operator and internal only, because tenant-facing generation could be reselling access (terms 2.6 v) or a competitive service (2.6 iv). Its outputs carry distribution: internal_only through every later derivation.

Who counts as the operator comes from metadata.authenticatedTenantId, which the routes stamp from verified credentials and strip from request bodies. A non-operator is refused 403 hosted_lane_operator_only, and while the exposure is operator_only nobody else sees the lane's catalog listing at all.

4. The rules every hosted request meets#

The policy lives in @isis/workflows and is applied at four places, so a job cannot slip past by taking a different door: at submit (which POST /jobs, /jobs/batch, /jobs/chain and the chain runner's later steps all reach), on retry (a retry re-submits, so the policy as it is now judges it, with the retrying caller's tenant), at execution (so a queued or recovered job is judged again before any vendor call), and in the catalog listing.

Common to both lanes:

  1. SFW only. Every hosted workflow is sfw_only, because the vendors' acceptable-use policies bind what Isis sends and the lane cannot police a vendor's refusal after the fact. A racy or explicit preset, a rating above neutral, or no rating at all is refused 422 content_policy_violation — an unreadable rating is not a neutral one. Where Meshy offers moderation, the lane turns it on and refuses a request that turns it off. Adult work stays on RunPod.
  2. Never a benchmark, comparison, evaluation or training input. OpenRouter's terms 7(4) forbid building a competing service; Meshy's 2.6(iv) forbids competitive analysis and 2.6(xi) training competing models on generated assets. A request declaring or flagging such a use is refused 403 hosted_lane_prohibited_use, and every output records the restrictions.
  3. Material the vendor may train on must declare its origin. OpenRouter 6.1 says some models train on inputs; Meshy's 2.9 says Meshy may train on inputs and outputs of non-Enterprise customers. So every file or URL sent declares operator_owned or tenant_upload. Operator-owned material is the platform's to send. A tenant upload needs a recorded vendor-training consent id naming the owning tenant; material of another tenant is refused to every actor, the operator included (tenant_boundary); undeclared material is refused. The provenance consentId is not reused for this. Every job carries one (the Studio sends a constant operator id), so its presence cannot mean a tenant agreed to send a file to a vendor that may train on it. The two ids are recorded side by side on the output. On the OpenRouter lane a tenant upload is refused outright while no vendor-training consent registry exists to check an id against (hosted_lane_vendor_training_consent_unverifiable) — an honest seam rather than a check that always passes.
  4. A consent id for the provenance ledger, refused before spending rather than after.
  5. Only documented request fields. The OpenRouter request body is parameters.openrouter; an undocumented key is refused rather than dropped on the floor, and every catalogue-gated parameter is checked against the checked-in snapshot, so the refusal costs nothing and names the allowed values. Meshy requests are held to each capability's documented fields the same way.
  6. No client-typed dispatch record. Only the lane writes providerJobId and providerEndpointId; a job carrying a forged one would be treated as a generation that has already been created and billed.
  7. AI identifiers preserved. Meshy's terms 2.4: outputs are stored byte for byte and nothing in the lane rewrites a file.

5. The clients and their snapshots#

One client per vendor, and each is pinned to a checked-in reading of the vendor's surface.

@isis/ai-providers/providers/openrouter-media is the one OpenRouter image and video client in the repository: image create (buffered and SSE), video create, poll and download, both catalogues and the per-model endpoint records. It is authenticated with a bearer token over https only, reads no environment (configuration is injected by the caller), and is idempotent by persisted job id — ensureVideo returns a recorded id without a POST and persists a new id before anything polls it. Every non-2xx answer is a typed error, and a 2xx body that is not the documented shape is OpenRouterInvalidResponseError, never a guess. Given a catalogue entry it refuses a request the catalogue does not support, and can refuse one whose estimate exceeds a ceiling — before spending.

openrouter-media-surface.snapshot.json is a checked-in reading of the live catalogues taken with the project key: the fetch date, the sha256 of each response, every image model with the fields the client relies on, every video model with its constraints and SKUs, and, for models the snapshot marks offerable, the per-provider endpoint records with their pricing.

offerable is a candidate set, not a decision to offer: the terms register decides that, and a model with no register row is not offered whatever the snapshot says. What offerable buys is the obligation that the snapshot carries enough pricing for an estimate to be produced or refused with a named reason — never guessed.

Two checks keep the client and the vendor from drifting apart silently: evaluateOpenRouterSurfaceCoverage (--check, offline) fails when the client calls a route the snapshot does not list, when a named model or parameter is absent, when an offerable model carries no usable pricing, or when the client's parameter tables and the catalogue have drifted in either direction; diffOpenRouterCatalog (--check-remote) names the models added, removed and repriced since the snapshot was taken.

The SSE line parser is shared between the OpenRouter and Meshy clients: it implements WHATWG HTML §9.2, which both vendors' streams follow, and holds no vendor policy. OpenRouter's own layer on top — unnamed data: events, a type discriminator inside the JSON, a [DONE] sentinel — is read in its own client.

6. The ledgers#

Each lane has a daily USD ledger, keyed per UTC day in Redis, and both fail closed: no Redis URL, or Redis unreachable, refuses the spend with ledger_unavailable. The in-memory ledger exists only for tests.

OpenRouter Meshy
What is recorded usage.cost — actual US dollars OpenRouter charged the account, not a conversion of a credit price. The task's own consumed_credits, converted at MESHY_USD_PER_CREDIT.
Idempotency Per generation id (images) or video job id. Per Meshy task id.
Failed jobs Not recorded at all: OpenRouter bills a completed generation in full or a failed one not at all. Credits are charged at creation and refunded when a task FAILS; a SUCCEEDED task reporting no number records the documented price and the line says so.
Budget ISIS_OPENROUTER_DAILY_BUDGET_USD, default $2. ISIS_MESHY_DAILY_BUDGET_USD, default $2 (100 credits at the rate below).
Gate Today's spend plus the catalog estimate must stay under the budget. Today's spend plus the documented price, checked at submit and again at task creation.

An estimate is never presented as what was charged. The catalog shows endpoint pricing for a stated default shape, labelled as an estimate; the money a job actually cost is the ledger's recorded figure. A shape with no priceable SKU is refused before it reaches the ledger.

The Meshy rate is a documented approximation with its source: Meshy's pricing page as served 2026-09-15 sells the Pro plan at USD 20/month for 1,000 credits, i.e. USD 0.02 per credit. The account's plan is not exposed by the API (the balance endpoint returns only balance), top-up credits may be priced differently, and an annual plan changes the effective rate — so the owner can set ISIS_MESHY_USD_PER_CREDIT to the rate actually paid.

7. Mixed chains#

A chain may cross lanes, and hostedChainRefusal decides each step from where its inputs came:

  • A hosted output may not feed an adult_ok workflow. The vendor's acceptable-use policy binds the output, and every offered model carries outputMayFeedAdultOk: false for exactly this.
  • A racy or explicit RunPod output may not be sent to a hosted step. The vendors' acceptable-use policies bind what Isis sends, so the restriction runs in that direction too.

This is the same shape as the self-hosted plate rule (content policy and distribution §6), with the lane as an extra fact about the input.

For 3D, the boundaries travel further, through evaluateThreeDDerivation: a derived mesh, a retexture, an animation, a library reuse or a final export is as restricted as its most restricted input. Distribution is internal_only when any input is; content is the highest rating of any input, and an input with no rating counts as explicit. A non-operator may not use an input that is internal_only however many derivations ago it entered; no actor, the operator included, may use an input owned by another tenant; and nothing widens at the audience — an internal_only output reaches only the operator, a tenant's material reaches only that tenant, and a file embedded verbatim whose registry row does not grant redistribution reaches only the operator.

8. Refusal codes#

All are answered as ordinary submit refusals — status and body, before the model cache, a job row or an outbox entry exists.

Code Lane Meaning
hosted_lane_operator_only both The exposure decision is operator-only.
hosted_model_unreviewed OpenRouter No register row; not offered rather than assumed fine.
hosted_model_excluded OpenRouter Excluded, with its recorded reason and reopensWhen.
hosted_model_task_mismatch OpenRouter The model does not serve that task.
hosted_lane_output_policy OpenRouter The mixed-chain rule of §7.
hosted_lane_tenant_boundary OpenRouter Material owned by another tenant.
content_policy_violation both Racy, explicit or unrated on an sfw_only lane.
hosted_lane_prohibited_use both Benchmark, comparison, evaluation or training use.
hosted_lane_input_origin_required both A file or URL was sent with no declared origin.
hosted_lane_vendor_training_consent_required both A tenant upload with no recorded vendor-training consent.
hosted_lane_vendor_training_consent_unverifiable both A tenant upload with no registry to check the id against.
hosted_lane_provenance_consent_required Meshy Raised by the generation API, which owns the provenance ledger's requirement.
hosted_lane_capability_excluded, hosted_lane_mode_unknown, hosted_lane_type_mismatch, hosted_lane_request_invalid, hosted_lane_input_url_unsupported, hosted_lane_moderation_required, hosted_lane_task_reference_requires_operator Meshy The capability, mode, type, request shape, input channel, moderation flag and task-reference rules of §4.
distribution_internal_only, tenant_boundary, distribution_widened, redistribution_prohibited, audience_invalid, content_policy_missing Meshy (derivations) The evaluateThreeDDerivation boundaries of §7.

9. Changing any of this#

  • Offering a new model: read the vendor's published terms, write the OpenRouterVendorTerms record with its verdicts, clauses, findings, open questions, fingerprint and evidence file, then add the offered row. A model cannot be offered without that reading; the spec treats an unlisted model as not offered.
  • Re-checking a terms document: openrouter-terms-drift.ts --check-remote. Text drift means a person re-reads the document — the tool never re-derives a verdict on its own.
  • Refreshing the surface snapshot: re-take it with the project key and run --check; a drift in either direction fails.
  • Changing an exposure decision: it is a checked-in constant with its date, source and reopensWhen. It changes by an owner decision recorded the same way, never by configuration.