openai_file_resolve

Resolves file_id and file_url references in Responses API input by fetching content from a Files API or remote URL via ApiClient and inlining the base64-encoded content in the provider-native field.

Praxis AI documentation version

On this page

Resolves file_id and file_url references in Responses API input by fetching content from a Files API or remote URL via ApiClient and inlining the base64-encoded content in the provider-native field.

Configuration Notes

The inference backend must support the resulting inline content part. This filter does not extract documents into backend-specific representations such as input_text.

This filter resolves references inside Responses requests; it does not proxy client-facing Files API operations. Route /v1/files and its subresources to the configured Files API with the standard router and load_balancer filters.

Configuration

Field	Type	Required	Description
`outbound_chain`	string \| object	no	Outbound filter chain applied to configured Files API (`file_id`) metadata and content requests. The chain runs through the `FilteredSubrequestExecutor`, so its filters observe and can mutate the outbound callout before it is dialed. SSRF protection for `files_api_url` derives from the pipeline’s `allow_private_upstreams`, enforced both when the callout target is pinned and at connect time. Client-controlled `file_url` downloads never traverse this chain; they stay on the credential-free hardened resolver. Optional. Configured `file_id` callouts always run through the bound outbound pipeline; this chain only adds filters along the way. When omitted it defaults to an empty inline chain (pure passthrough) via `default_outbound_chain`, so registration never fails for a missing chain — matching `openai_file_search_callout`. Provide it only to attach cross-cutting concerns such as credential injection, tracing, or request tagging. May be defined inline (`name` + `filters`) or reference a top-level named chain; a named reference resolves because this filter runs at the top pipeline level, not nested inside an `iterative_request_router` step. Registration still fails the build when a provided chain cannot be bound.
`allow_pre_security_callout`	bool	no	Allow Files API callouts from the `StreamBuffer` pre-read phase, before header-phase security filters execute. This must be explicitly enabled only when an outer trust boundary authenticates and authorizes requests before they reach this listener. Forwarded headers are the original downstream values, not mutations from request filters.
`files_api_url`	string	yes	Base URL of the Files API endpoint. Example: `http://files-api:8321`
`user_credential`	string	no	Optional callout-credential slot. When configured, Files API `file_id` requests use that caller-scoped value as their `Authorization` header. Client-controlled `file_url` fetches never use this credential.
`forward_headers`	string[]	no	Headers to forward from the original request to the Files API for authentication and tenant isolation. No downstream headers are forwarded by default.
`max_rewritten_body_bytes`	integer	no	Maximum size in bytes of the request body this filter produces after inlining resolved `file_id` / `file_url` content (default 64 MiB). Raw request body size is governed by the pipeline’s `body_limits`, not this field. The resolved body can grow larger than the raw input because references are replaced with inline content.
`max_resolved_bytes`	integer	no	Maximum total size in bytes of inline file content this filter adds to one request (default 64 MiB). Charged against the encoded inline form — base64 `file_data` and `data:` URL `image_url` values — not the raw bytes fetched from the Files API or remote URL, and shared as a single budget across every reference resolved in the request rather than applied per file. A file whose raw content would fit can still be rejected once base64 expansion is counted, and several individually small files can exhaust the budget together. Bounds inline expansion independently of the total rewritten body size (`max_rewritten_body_bytes`).
`max_file_references`	integer	no	Maximum number of distinct content-part / `file_id` pairs to resolve in one request, including rehydrated history.
`on_missing`	`continue` \| `reject`	no	Behavior when a `file_id` reference cannot be fetched. Does not apply to `file_url`: a failed `file_url` fetch is always rejected, regardless of this setting.
`timeout_ms`	integer	no	HTTP timeout in milliseconds for Files API callout requests. Inside an iterative request router, the effective timeout is capped by the router’s remaining deadline.
`file_url`	`resolve` \| `passthrough`	no	Mode for `file_url` content parts in `input_file`.
`allowed_file_url_origins`	string[]	no	Exact origins allowed to resolve to private addresses. Cloud metadata, unspecified, and multicast remain blocked.

Examples

Example 1

filter: openai_file_resolve
files_api_url: "http://files-api:8321"
allow_pre_security_callout: true
outbound_chain:
  name: files-api-outbound
  filters:
    - filter: headers
      request_set:
        - name: x-file-callout
          value: file-resolve

Example 2

filter: openai_file_resolve
files_api_url: "http://files-api:8321"
allow_pre_security_callout: true
outbound_chain:
  name: files-api-outbound
  filters:
    - filter: headers
      request_set:
        - name: x-file-callout
          value: file-resolve
forward_headers:
  - authorization
  - x-tenant-id
on_missing: continue
timeout_ms: 30000
max_rewritten_body_bytes: 67108864
max_resolved_bytes: 67108864
max_file_references: 32

Example 3

filter: openai_file_resolve
files_api_url: "http://ogx:8321"
allow_pre_security_callout: true
outbound_chain:
  name: ogx-outbound
  filters:
    - filter: headers
      request_set:
        - name: x-file-callout
          value: file-resolve
file_url: resolve
allowed_file_url_origins:
  - "https://files.internal:8443"