This guide shows how to integrate the Phase 75 Universal Originality Shield into generation, upload, and publication pipelines. It covers HTTP client usage, embedded gateway usage, media-specific payloads, configuration, error handling, and performance tuning.
Use createShieldApiClient().universalScan() when a product service calls the
Shield API over HTTP. Use UniversalShieldGateway directly only when the scan
adapters run in the same process as the generation or ingestion worker.
Integration Flow#
- Assign a stable
generationIdand request-scopedscanId. - Build a
UniversalShieldScanRequestBodywith either onecontentitem or acomponentsarray for compound media. - Set
domainto the calling domain, such ascalliope,isis,hathor,veritas,maya, oryemaya. - Submit the scan with
client.universalScan()orgateway.scan(). - Branch on
actionRequired. - Store the scan response, routed shield ids, component findings, reference ids, and the publication decision with the generation record.
- Route
review,remediate, andrejectoutcomes to the review or remediation pipeline before publication.
Default Universal Shield actions are:
| Risk level | actionRequired |
Default handling |
|---|---|---|
pass |
none |
Publish and retain the audit record |
advisory |
none |
Publish with monitoring and provenance retention |
flag |
review |
Hold publication for trained reviewer assessment |
high_risk |
remediate |
Hold publication and create a remediation package |
reject |
reject |
Block publication until legal or policy override |
Install And Configure#
The shield API client is exported from @themis/shield-api in this workspace.
Application packages normally depend on the published package or workspace
package:
pnpm add @themis/shield-api
Set the API base URL and one authentication mechanism:
THEMIS_SHIELD_API_URL=https://shield.internal.example.com
THEMIS_SHIELD_API_KEY=replace-with-service-key
Use bearerToken instead of apiKey when the caller authenticates with a JWT
issued by the platform identity layer.
import { createShieldApiClient } from '@themis/shield-api';
export const shieldClient = createShieldApiClient({
baseUrl: process.env.THEMIS_SHIELD_API_URL ?? 'http://localhost:8787',
apiKey: process.env.THEMIS_SHIELD_API_KEY,
headers: {
'x-service-name': 'isis-generation-worker',
},
});
Universal Scan Payload#
Use content for a single artifact:
import { shieldClient } from './shield-client.js';
export async function scanImageGeneration(input: {
readonly generationId: string;
readonly imageUrl: string;
readonly prompt: string;
readonly modelId: string;
}): Promise<void> {
const response = await shieldClient.universalScan({
scanId: `image-${input.generationId}`,
generationId: input.generationId,
domain: 'isis',
mediaType: 'image',
content: {
kind: 'url',
data: input.imageUrl,
contentType: 'image/png',
filename: `${input.generationId}.png`,
metadata: {
prompt: input.prompt,
modelId: input.modelId,
},
},
metadata: {
releaseGate: 'pre_publish',
workflow: 'text_to_image',
},
});
await applyUniversalShieldDecision(input.generationId, response);
}
Use components for compound content where multiple media types must be
evaluated together:
const response = await shieldClient.universalScan({
scanId: `music-video-${generationId}`,
generationId,
domain: 'calliope',
components: [
{
componentId: 'soundtrack',
role: 'music_track',
mediaType: 'music',
content: {
kind: 'url',
data: audioUrl,
contentType: 'audio/wav',
},
},
{
componentId: 'lyrics',
role: 'lyric_sheet',
mediaType: 'text',
content: {
kind: 'text',
data: lyrics,
contentType: 'text/plain',
},
},
{
componentId: 'video-render',
role: 'final_video',
mediaType: 'video',
content: {
kind: 'url',
data: videoUrl,
contentType: 'video/mp4',
},
},
],
metadata: {
releaseGate: 'final_publish',
compoundPolicy: 'music_video',
},
});
The response includes:
detectedMediaTypes: normalized media types scanned.routedShieldIds: adapters used by the gateway.componentResults: per-component findings, scores, and reference ids.compoundMatches: cross-component matches that may raise the overall risk.overallRiskLevelandactionRequired: the publication gate decision.
Media Type Steps#
Use the same scan flow for every media type. The difference is how the content is encoded and which metadata helps reviewers and audit trails.
| Media type | Content guidance | Required metadata to include |
|---|---|---|
audio |
WAV, FLAC, MP3, or object storage URL | duration, sample rate, channel count |
music |
final mix, stems, melody, or MIDI-like object | prompt, model, genre, tempo, contributors |
voice |
utterance audio or voice embedding reference | consent id, speaker claim, locale |
image |
PNG, JPEG, or source image URL | prompt, seed, model, dimensions |
text |
generated text, prompt output, script, or lyrics | prompt, source task, language |
video |
MP4, MOV, WebM, storyboard bundle, or keyframes | duration, fps, model, shot list |
model_3d |
GLB, glTF, OBJ, FBX, or topology object | asset class, topology stats, source tool |
motion |
keyframes, BVH-like data, or mocap clip URL | frame rate, rig type, capture source |
character |
character sheet, profile, or model bundle | archetype, silhouette tags, prompt |
fashion |
garment render, pattern, or tech pack | garment type, pattern source, collection |
environment |
level layout, scene graph, or environment render | map size, landmarks, asset pack ids |
Audio, Music, And Voice#
Use audio for generic sound effects and recordings, music for composition
and track-level scans, and voice for voice likeness or consent-sensitive
output. These media types route to music_shield.
await shieldClient.universalScan({
generationId,
domain: 'calliope',
mediaType: 'voice',
content: {
kind: 'url',
data: voiceClipUrl,
contentType: 'audio/wav',
metadata: {
consentId,
speakerDisplayName,
locale: 'en-US',
},
},
});
Image And Video#
Use image for single-frame outputs and video for rendered clips,
storyboards, or shot sequences. Include prompts, model versions, source
references, and dimensions so reviewers can reproduce context.
Text#
Use text for prose, dialogue, lyrics, prompts, captions, scripts, and
metadata-heavy story exports. Include the generation prompt and any source
constraints. Do not strip paragraph order before scanning; sequence similarity
is part of the signal.
3D, Motion, Character, Fashion, And Environment#
Use structured object payloads when the artifact is not yet exported:
await shieldClient.universalScan({
generationId,
domain: 'yemaya',
mediaType: 'model_3d',
content: {
kind: 'object',
data: {
mediaType: 'model_3d',
meshes: meshSummaries,
vertices: vertexCount,
materials: materialFingerprints,
},
metadata: {
sourceTool: 'procedural-kitbash-worker',
assetClass: 'vehicle_prop',
},
},
});
Use components when a character has a visual sheet, 3D model, costume pack,
and animation all tied to one release decision.
Embedded Gateway Integration#
Use UniversalShieldGateway directly when adapters run in-process:
import {
UniversalShieldGateway,
type UniversalShieldAdapter,
} from '@themis/shield-api';
const adapters: readonly UniversalShieldAdapter[] = [
musicAdapter,
visualAdapter,
textAdapter,
videoAdapter,
model3dAdapter,
motionAdapter,
characterAdapter,
fashionAdapter,
environmentAdapter,
];
export const universalShield = new UniversalShieldGateway({ adapters });
const response = await universalShield.scan({
scanId: `embedded-${generationId}`,
generationId,
domain: 'hathor',
mediaType: 'text',
content: {
kind: 'text',
data: sceneText,
contentType: 'text/plain',
},
});
Adapters must return a UniversalShieldComponentScanResult with a stable
componentId, mediaType, shieldId, status, riskLevel, score,
findings, and optional referenceWorkId.
Decision Handling#
Keep publication logic small and auditable:
import type { UniversalShieldScanResponse } from '@themis/shield-api';
type PublicationDecision =
| { readonly action: 'publish'; readonly reason: string }
| {
readonly action: 'review';
readonly queue: string;
readonly reason: string;
}
| { readonly action: 'remediate'; readonly reason: string }
| { readonly action: 'reject'; readonly reason: string };
export function decisionForUniversalShield(
response: UniversalShieldScanResponse
): PublicationDecision {
switch (response.actionRequired) {
case 'none':
return {
action: 'publish',
reason: 'Universal Shield passed the release gate.',
};
case 'review':
return {
action: 'review',
queue: reviewQueueFor(response),
reason: 'Reviewable similarity requires human assessment.',
};
case 'remediate':
return {
action: 'remediate',
reason: 'High-risk similarity requires content remediation.',
};
case 'reject':
return {
action: 'reject',
reason: 'Release-blocking similarity detected.',
};
}
}
Persist the full response with the generated artifact. Do not persist only the final action; downstream audit, legal review, and quality analysis need the component-level details.
Error Handling#
HTTP callers should handle these classes of failure:
| Condition | Handling |
|---|---|
400 invalid input |
Treat as integration bug; log request shape and block publication |
401 unauthorized |
Refresh credentials or rotate service key; do not retry indefinitely |
429 rate limited |
Retry with backoff and leave the generation unpublished |
5xx server error |
Retry with bounded backoff; escalate if the release gate deadline expires |
501 no gateway |
Misconfiguration; enable universalScan handler before routing traffic |
| failed scan response | Block publication and send the scan id to operations for triage |
When retrying, reuse generationId and use a stable or idempotent scanId
derived from the generation and release gate. This prevents duplicate audit
records for the same artifact.
Configuration Checklist#
Each domain integration should define:
- Which release gates call the shield: preflight, preview, final publish, import ingestion, remix export, or marketplace listing.
- Which media types are possible in that domain.
- The adapter set enabled in each environment.
- Request size limits and whether large artifacts must use
urlor object storage references. - Review queues for
flagresults by media type. - Remediation behavior for
high_riskresults. - Hard block policy for
rejectresults. - Audit retention policy for the scan response and publication decision.
- Jurisdiction and consent metadata required for voice, biometric, or likeness sensitive output.
Performance Tuning#
Baseline latency targets are tracked in
UNIVERSAL_SHIELD_PERFORMANCE_REGRESSION_BASELINE:
| Scan type | Target |
|---|---|
| image, audio, music | under 5s |
| text | under 10s |
| 3D, motion, scene | under 15s |
| video | under 60s |
| compound music video | under 90s |
| concurrent throughput | 20 scans/s |
| memory delta | under 64MiB |
For production callers:
- Prefer object storage URLs for video, 3D, and compound scans.
- Use
quickScanonly for music-specific fast preflight; useuniversalScanfor cross-media publication gates. - Batch generation worker submissions by release stage, not by unrelated user sessions.
- Cache reference lookups by
referenceWorkId, but never cache final scan decisions across distinct artifacts. - Record queue wait time separately from scan execution time.
- Run
runUniversalShieldPerformanceBenchmarks()after adapter changes and compare results to the regression baseline before deployment.
Verification#
Before merging a new domain integration:
pnpm nx typecheck @themis/shield-api
pnpm nx test @themis/shield-api
pnpm nx lint @themis/shield-api
pnpm nx build @themis/shield-api
pnpm exec tsx scripts/themis/run-universal-shield-continuous-validation.ts \
--report-file /tmp/themis-shield-continuous-validation-report.json \
--trigger manual \
--fail-on-alerts
Add or update tests when an integration changes routing, risk mapping, component construction, review decisions, remediation, or audit persistence.