An AI creative production API should return more than a downloadable file. Once an image, video, voice track or avatar enters a real campaign workflow, the binary is only one part of what a production team needs. The surrounding record determines whether the asset can be found, reviewed, reproduced, licensed, delivered in another format and traced back to its source.
This distinction matters for brands, agencies, studios and publishers working across multiple production stages. A campaign image may become an ecommerce crop, a social edit, a video reference or part of a broadcast package. A file without context quickly becomes difficult to manage.
The file needs a stable identity
Every completed job should have durable identifiers: a request ID, job ID, asset ID and, where relevant, the IDs of parent assets. The response should also include status, creation time and an asset or schema version.
These fields make asynchronous production practical. A client can safely poll a job, retry a failed request, connect several outputs to the same brief and give support teams something more useful than “the download did not work.” They also establish lineage when one image becomes a reference for a video or when a revised asset replaces an earlier version.
Delivery information should be separate from the binary
A signed download URL is useful, but it should not be the entire delivery response. The API should identify the URL’s expiry time, storage key, MIME type, file size, dimensions and checksum. For video, duration, frame rate and frame count may also matter. For image work, available renditions, transparency support, color profile and compression settings can determine whether the result is ready for a particular channel.
Separating delivery metadata from the asset itself also makes multi-format production easier. A single creative record can point to a master file, a web-optimized version, a transparent export and a preview without losing the relationship between them.
The recipe makes the result reproducible
A useful response records the effective generation recipe, not merely the user’s first instruction. That may include the normalized prompt, any prompt-rewrite result, negative prompt, model and model version, seed, aspect ratio, dimensions, quality settings and reference-asset IDs.
This is essential when a team needs to revise a campaign without starting from an unknown state. It also helps distinguish a creative change from a tool or workflow change. A seed can support deterministic or near-deterministic production in systems that provide that capability, while a versioned workflow records which production logic was applied.
For a connected studio, this record should extend beyond a single image generator. The workflow may include product preparation, photographic direction, video generation, motion transfer, avatar performance or voice production. Ruwana’s connected production workflow reflects this broader view: direction and context should travel with the work instead of being rebuilt in every tool.
Safety results should be structured and visible
A generic “request failed” response is inadequate for commercial production. The API should distinguish input moderation from output moderation and expose a status, policy version, reason code and, where appropriate, category scores. It should also indicate whether the output was blocked, filtered, transformed or delivered with a warning.
Structured safety results help teams route work correctly. A blocked prompt, an unsafe generated image, an expired reference URL and an unsupported aspect ratio are different operational problems. They require different fixes, and they should not be hidden behind the same error message.
Provenance and lineage belong in the creative record
Commercial teams increasingly need to understand where an asset came from and what happened to it. A response can provide provenance status, the generating tool or model, a verification reference and any available Content Credentials. The status should distinguish between valid, missing, unverified and invalid provenance.
The C2PA specifications describe a way to attach cryptographically bound provenance information to media, including origin, modifications, tools and AI-use assertions. This does not prove that every claim about an asset is true, and credentials may not survive every transformation. It does provide a more useful basis for review than an unlabelled file.
Lineage should cover source assets, operations, agents or services involved, parent-child relationships and timestamps. For a retailer, that might connect a product reference to a hero image, a transparent packshot and a short product video. For a broadcaster, it might connect a generated scene, its revisions and the final edit. Teams working with multi-format delivery can see a related production perspective at Turn TV, where the relationship between creative assets and channel output is central.
Usage and quality signals make production measurable
Production systems also need an accounting layer. The response can report input and output units, generation duration, credits consumed, estimated cost and a billing reference. That information allows a marketing team to connect a campaign asset to usage, while an internal production team can identify expensive stages or repeated work. Ruwana’s plans and credits are easier to manage when usage is attached to a clear production record rather than left inside an opaque tool session.
Quality signals should be similarly practical. Resolution checks, requested-format compliance, OCR or text-rendering warnings, face and object detection warnings, transparency support and visual QA status can all help downstream systems decide what happens next. These are signals for review, not an automated declaration that a creative result is objectively good.
A response designed for real systems
A concise response structure might look like this:
{
"data": {
"asset": { "id": "asset_123", "type": "image", "status": "ready" },
"delivery": { "url": "…", "expires_at": "…", "mime_type": "image/png" },
"recipe": { "model_version": "…", "seed": 42, "width": 2048, "height": 2048 },
"provenance": { "status": "verified", "credentials": "…" },
"safety": { "status": "passed", "policy_version": "…" },
"lineage": { "parent_asset_ids": [] },
"usage": { "credits": 12 },
"quality": { "status": "passed" }
},
"meta": {
"request_id": "req_123",
"idempotency_key": "campaign-brief-07",
"api_version": "v1",
"created_at": "…"
},
"errors": []
}
The exact schema will vary, but the principle is stable: a file is an output, while a production record is an operational asset. When creative work must move through review, rights management, a DAM, ecommerce, publishing or broadcast, the metadata is what makes the output usable at scale. Teams should also define retention, rights and customer responsibilities clearly, alongside the technical response; Ruwana’s Terms of Use provide the appropriate legal context for those questions.


















