Resources · Output Contracts

Unified Output Contracts

A production contract spec that keeps responses stable across text, voice, image, and video providers.

Canonical Response Contract

{
  "success": true,
  "content": "Primary human-readable output",
  "provider": "openai",
  "usage": {
    "input_tokens": 120,
    "output_tokens": 64
  },
  "metadata": {
    "model": "gpt-x",
    "latency_ms": 540,
    "trace_id": "trc_123"
  },
  "images": [],
  "files": [],
  "videos": []
}

Design Principles

One envelope for all modalities and providers.
Field names remain stable across runtime versions.
Provider-specific details live in metadata, not top-level shape drift.
Missing modality outputs return empty arrays, not shape changes.
success flag is mandatory for deterministic client handling.

Field Reference

success: boolean operation outcome.
content: primary human-readable output.
provider: normalized provider identifier.
usage: normalized accounting object.
metadata: diagnostics and execution context.
images/files/videos: modality output arrays.
error: structured error object when success=false.

Multi-Provider Examples

OpenAI-style normalized response

{
  "success": true,
  "content": "Generated response",
  "provider": "openai",
  "usage": { "input_tokens": 90, "output_tokens": 52 },
  "metadata": { "latency_ms": 480 },
  "images": [],
  "files": [],
  "videos": []
}

Replicate-style normalized response

{
  "success": true,
  "content": "Image generation completed",
  "provider": "replicate",
  "usage": { "input_tokens": 0, "output_tokens": 0 },
  "metadata": { "duration_ms": 2300 },
  "images": [{ "url": "https://..." }],
  "files": [],
  "videos": []
}

Client Compatibility Rules

Frontend rendering logic should depend on envelope shape, not provider internals.
Clients must tolerate unknown metadata keys for forward compatibility.
Empty arrays are valid outputs for non-applicable modalities.
Parsing should prefer explicit field checks over provider branching.

Error Contract

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request payload",
    "details": {}
  },
  "provider": "system",
  "metadata": {
    "trace_id": "trc_123"
  }
}

Error payloads must include machine-readable code and human-readable message.
Trace identifiers should be propagated for diagnostics.
success=false responses should never reuse success payload-only fields.
HTTP status and structured error code must remain consistent.