Media

Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified.

Planned API origin. Examples use https://noemad.dev/v1, the intended product API path. The API is not connected in this frontend preview. MODEL_ID_FROM_DISCOVERY and NOEMAD_API_KEY are placeholders, not published credentials or model IDs. A product API key identifies an account; a separate payment-aware transport must handle spending authorization.

Endpoint families

Media controls are model-specific. An input file is not authorized merely because the UI can select it. The server validates content, size, ownership, supported types, and cost modifiers before admission.

Image generation

{
  "model": "MODEL_ID_FROM_DISCOVERY",
  "prompt": "A marble observatory above an ancient Greek coastline.",
  "size": "1024x1024",
  "quality": "medium",
  "n": 1,
  "response_format": "b64_json"
}

Only offer sizes, quality settings, counts, and response formats supported by the adapter. An image response may contain encoded bytes or an expiring URL. Check its actual MIME type and dimensions; the filename alone is not evidence.

The archive distinguishes GPT image variants and two Imagine image versions. Some have separate quality, resolution, aspect-ratio, and editing controls. Those archived names do not imply that the corresponding route is enabled in Noemad.

Image edits and uploads

POST /v1/images/edits
Content-Type: multipart/form-data; boundary=BOUNDARY
Idempotency-Key: SAME_LOGICAL_EDIT_KEY

model = MODEL_ID_FROM_DISCOVERY
prompt = Extend the courtyard, keeping the central statue.
image = <validated local image bytes>
# Add size, mask, quality, or extra images only when supported.

Do not base64-wrap a file when the chosen endpoint requires multipart. Validate each source independently, apply count and resolution limits, and quote any extra-input surcharge. A retry keeps the same idempotency key and body.

An upload returns an owner-scoped file ID only after acceptance. Map it to the provider reference on the server. Do not expose a shared provider file catalog or let one wallet retrieve another wallet’s files.

Durable video jobs

{
  "model": "MODEL_ID_FROM_DISCOVERY",
  "prompt": "A slow camera orbit around a marble astronomical instrument.",
  "duration": 6,
  "resolution": "720p"
}

queued → running → succeeded
               ↘ failed
               ↘ unknown → reconcile
Owner reads GET /v1/videos/{id} for the same durable job.

Persist the accepted job ID before polling. The create response may indicate that the job is still preparing or queued. Honor server polling guidance and stop when a terminal state is confirmed.

A client reconnect or worker restart resumes the same job. An unknown create outcome is not permission to create another paid video. Publish cancellation and expiration semantics only once the adapter can prove them.

A completed response must include verified duration, size, format, and a scoped result grant. Missing or invalid artifacts are not successful delivery merely because the provider job says completed.

Speech synthesis and transcription

{
  "model": "MODEL_ID_FROM_DISCOVERY",
  "input": "Welcome to Noemad. Let us turn an idea into a result.",
  "voice": "VOICE_FROM_DISCOVERY",
  "response_format": "mp3"
}

Speech synthesis validates text length, voice, language, speed or style controls, and output encoding. Stream or return audio only with the correct content type. A playable artifact and its delivered duration are part of the completion check.

POST /v1/audio/transcriptions
Content-Type: multipart/form-data; boundary=BOUNDARY

model = MODEL_ID_FROM_DISCOVERY
file = <audio bytes>
language = en
response_format = json

Transcription validates duration, encoding, file size, and any supported language hint. The result may include text, segments, or timestamps only when the selected format declares them. Invalid or incomplete transcripts must remain errors.

Artifact ownership and expiry

A download grant is scoped to one owner and artifact. It can expire independently of the operation record. Display its expiry and provide a documented way to obtain a new grant if supported. Do not construct an undocumented download URL from a job ID.

Before serving bytes, validate size, content type, and allowed disposition. Apply an explicit retention and deletion policy before production; this frontend does not promise permanent media hosting.

Quote the modality’s real unit

The client authorizes a maximum derived from enforceable limits. The service settles attributable actual usage afterward. Failed or uncertain delivery follows the declared profile policy; missing usage never permits an automatic maximum debit. See Billing & limits.

Preview behavior

The media workspace exposes local sample controls and state transitions. It does not upload selected files, contact a model, generate media, or create a payment. The site’s decorative backgrounds and animated illustrations are original frontend assets, separate from inference outputs.