How to Integrate OpenAI's Content Provenance API: 2026 Developer Workflow

Use OpenAI's Content Provenance API in your upload review flow when you need to check for supported OpenAI provenance signals. It is not a universal AI detector: a not_detected result does not show that a file was made without AI.

This guide is for developers building content moderation or fact-checking features, technical leads planning image-source checks, and engineers maintaining media upload services.

Before integration: confirm which signals matter

Start by defining the decision your product needs to support. The API checks for supported OpenAI provenance signals. It does not determine whether an image or audio clip is truthful, authentic, unedited, or made by any AI system.

That distinction affects both your interface and your storage design. A provenance check can provide evidence about a supported signal. It cannot settle questions about the depicted event, the identity of a speaker, edits made after generation, or whether a post gives the media accurate context.

OpenAI documents two signal families that matter here. C2PA Content Credentials are provenance metadata associated with media. SynthID is a watermarking signal used in supported OpenAI-generated content. The signals are different, and their coverage depends on the product, model, file type, and processing path. Check the OpenAI explanation of Content Credentials and SynthID coverage before promising what your product can identify.

Signal or source	What your review can check	What a positive result does not establish
C2PA Content Credentials	Whether supported provenance metadata is present and recognized in the submitted media. The C2PA specification's Content Credentials guidance describes how credentials relate to media and its processing.	That the depicted scene is real, that the file has never been edited, or that its current context is accurate.
SynthID	Whether a supported SynthID watermark signal is found in eligible image or audio content, as described in OpenAI's signal coverage notes.	That all media from a given tool carries the signal, or that other AI-generated content will be detected.
Other AI provenance or no supported signal	The API may return no supported signal for content outside its coverage or for files whose signals are unavailable.	That the file was made by a person or that it has no AI-derived content.

Can the OpenAI verification API detect images from other AI tools? Do not design around that assumption. Its purpose is checking supported OpenAI source signals, not identifying every generator. If your product must cover other tools, treat this API as one evidence source and plan separate, appropriately validated checks rather than presenting it as a universal classifier.

The practical choice is to make this a provenance check, not a verdict. Give the result a narrowly scoped label in your product, such as “supported source signal found” or “no supported signal found.” Avoid labels like “real,” “fake,” or “human-made” unless other evidence independently supports those claims.

Before calling: place the check in the media flow

Decide where verification belongs before connecting the endpoint. An upload-time check can inform an initial review queue. A pre-publication check can prevent a post from going live until a review state is resolved. A post-publication check may suit systems that need to assess existing uploads or reprocess media after changing their policies.

Choose based on the consequence of a missed or delayed check. If uploads are large, users can retry, or the review service is sometimes unavailable, blocking the whole upload on a provenance result may create a poor failure mode. You can accept and quarantine the file, then complete the check asynchronously. If publication must wait for review, hold publication rather than treating a timeout as a clean result.

Before you send media, record the policy decisions your service needs to preserve:

Which original file or stable file reference was checked.
When the check was requested and which policy version routed its result.
Whether the API call completed, failed, timed out, or returned an outcome your adapter does not recognize.
The documented signal and result information needed for review.
Whether a reviewer changed the disposition, and the reason for that decision.

Do not store more user content or personal information than your workflow needs. In particular, avoid putting access tokens, full request bodies, or unnecessary media contents in general-purpose application logs. Keep credentials in server-side secret storage and limit access to review records.

The Content Provenance API guide and the create-check API reference are the sources to consult for the current request format, file support, SDK method, and response schema. Those details can change. Confirm that your actual upload format and current SDK version are supported before you build around a specific request shape.

During integration: call the API and preserve the response

The documented Python reference exposes a create method for a content provenance check. Follow its current signature and file requirements rather than copying an old integration from a blog or code sample. The following shows the shape of a server-side call; verify the accepted parameter names and file handling against the live reference before using it in your service:

from openai import OpenAI

client = OpenAI()

with open("upload.png", "rb") as media:
    response = client.content_provenance_checks.create(
        file=media
    )

print(response.model_dump_json(indent=2))

The example submits the media file through the SDK and prints the returned object for inspection. Do not assume that a field name, enum value, or nested result path from an older response will remain valid. During implementation, compare the response with the current API reference and capture a reviewed fixture for each response state your application supports.

Build a small adapter between the API response and your product's moderation model. That adapter should read the documented signal type, detection result, and verification status from the current response schema. Keep the API-specific field mapping in one place. Then return an internal state that your moderation system can act on:

A supported signal is reported: preserve the signal information and send the item to the policy or review path that uses that evidence.
No supported signal is reported: record that limited outcome, but do not mark the content as non-AI.
The result is missing, unrecognized, or incomplete: route to manual review or a retry policy; do not silently convert it to “no signal.”
The request fails: record a technical failure state that is distinct from both detection outcomes.

Does not_detected mean the image is not AI-generated? No. OpenAI's guidance says an absent result may be consistent with metadata being stripped, a watermark degrading, an older model, or another AI source. Preserve the distinction between “no supported signal found” and “verified non-AI.” The official coverage and limitation notes are essential when you choose user-facing wording.

Application state	Evidence available	Recommended action
Supported signal found	The API reports a recognized supported source signal for the submitted media.	Store the documented result and apply your content policy. Use human review if the decision affects access, reputation, or safety.
No supported signal found	The API did not find a supported signal in the submitted file.	Continue with other checks. Do not describe the content as human-made or authentic based on this result alone.
Unknown or incomplete response	Your adapter cannot safely interpret the response, or required result information is absent.	Keep the item in a review or retry state. Alert the service owner if the response is unexpected.
Request error or timeout	The API call did not complete successfully.	Preserve a technical failure state. Retry only under a documented policy, or send the item to a human queue.

These mappings are product decisions, not API verdicts. Make your moderation policy explicit about what happens when a supported signal appears. A provenance signal can justify additional scrutiny or a label, but a signal should not automatically trigger a claim that the media is deceptive.

After integration: test the boundaries before release

Test the full media path, not just the API call. Provenance metadata can be affected by how your service accepts, stores, transforms, and forwards files. A check against a file converted by an image-processing job may not give the same evidence as a check against the original upload. Keep an immutable reference to the source file when your retention rules allow it, and record which file version was submitted for verification.

Use a test matrix that covers your own upload and review behavior:

Submit each file type you intend to support, then verify it against the file requirements in the current API guide.
Compare the original upload with files that pass through your own resizing, transcoding, or metadata-stripping stages.
Test the supported-signal, no-supported-signal, timeout, rejected upload, and unexpected-response paths.
Confirm that an API error cannot fall through to a default “clear” or “not AI” state.
Check that review staff can see the signal result, its limitations, and the file version that was checked.
Confirm that logs do not expose credentials or retain unnecessary media data.

For rate handling, distinguish traffic control from provenance interpretation. The official rate-limit guidance explains how to handle API limits. Add bounded retries only where they fit your workflow, and make retry exhaustion visible as a technical state. Do not turn a rate-limit response into a negative detection result.

For other failures, use the official API error-code guidance to classify errors and choose whether to retry, defer, or surface an operational alert. Your product should preserve the reason a check did not complete, while limiting user-facing detail to what helps the user understand the review status.

Use these decision branches for launch scope

If you need to check only for supported OpenAI provenance signals, and your media types match the current documentation, integrate the API as one step in your review pipeline.
If you need to identify content from any AI tool, do not use this API as the sole detector. Choose a broader review strategy and describe what each signal can and cannot show.
If publication can wait for a completed review, hold publication when the check is pending or failed. If it cannot wait, allow the upload only under a separate policy that does not imply verification.
If your service transforms media before checking, verify the transformed-file behavior and retain a reference to the original. If you cannot preserve or inspect the relevant file version, route uncertain cases for review.
If your team cannot maintain response-schema tests and failure handling, postpone automated decisions. Start with a human review queue and a narrowly scoped provenance label.

This is a launch decision, not a promise of detection coverage. Recheck the API guide, request reference, and signal notes whenever you change supported file types, SDK versions, upload transformations, or moderation policy.

Choose the runtime that matches the work

The verification request itself is an API integration task; it does not require a Mac just because it processes image or audio files. A local development machine can be enough for a small proof of concept. The trade-off changes when your product also needs a persistent test host, a shared review environment, or repeated builds and tests that depend on macOS.

Runtime option	Strong fit	Main trade-off
Existing developer machine	A short-lived API prototype or debugging a small set of uploads.	Tests compete with other work, and the environment may not stay available to teammates.
Existing server or cloud runtime	A continuously running upload and moderation service.	You must operate the service, protect credentials, manage retries, and monitor API failures.
Rented Mac environment	A temporary shared environment for macOS-dependent builds or end-to-end client testing.	It is unnecessary if your only requirement is to call the provenance API from a server.

For your implementation, judge the choices by operational fit rather than assuming one host improves detection. A server-side integration can be more suitable for a persistent media pipeline; a Mac environment may help when your client, build, or end-to-end test process specifically depends on macOS. If the work is long-running and consistently busy, compare rental costs and operating requirements with buying and maintaining your own machine.

When you need a temporary macOS test environment alongside the moderation work, review VPSSpark's available Mac environments before committing to hardware. If you need to check which setup fits your testing workflow, contact VPSSpark support. Rent only when the Mac-dependent work justifies it; do not add a Mac to the architecture simply to make an API call.

Ship a review state, not a verdict

A sound integration has a narrow contract: submit a supported file, interpret only documented response fields, preserve the checked file version, and route uncertainty without disguising it as a negative result. Your users should be able to tell the difference between a supported signal, no supported signal, and a check that did not complete.

That separation is the core safety property. It lets your moderation team use provenance evidence without claiming more than the API can establish. When you expand formats or change upload processing, rerun the boundary tests and revalidate the current documentation before treating the new path as covered.