media.audio.transcribe

Transcribe an audio StorageObject via the org AI connection (provider-blind), persist the transcript to storage, and index it as a copy GeneratedArtifact. Returns refs plus the transcript text; audio bytes never enter workflow state.

Overview

Property	Value
Workflow type	Atomic
Library	App-media
Version	1.0

Input Schema

Field	Type	Required	Default	Description
workflow_run_id	string	No	—	Parent DAG workflow run id (engine-injected when used as a step)
organization_uuid	string	Yes	—	—
storage_object_uuid	string	Yes	—	StorageObject UUID of the audio to transcribe. Produce one with media.ingest.from-url (remote URL) or storage.upload.presigned-url (browser/direct upload).
media_profile_uuid	string	No	—	Optional MediaProfile supplying storage connection + bucket + key_prefix. Unlike media.image.*, a draft profile is accepted: profile readiness is an image-smoke verdict and does not gate audio.
ai_provider_config_uuid	string	No	—	AIProviderConfig to source the AI connection from; defaults to the org default
connection_uuid	string	No	—	Explicit AI CloudConnection UUID. Any connection serving the OpenAI /audio/transcriptions contract works; a non-native type can opt in with supports_transcription=true on its config.
model	string	No	—	Transcription model, or the Azure deployment name. Falls back to the resolved AIProviderConfig's default_model, then to whisper-1. Bind a dedicated STT provider config and this can be omitted.
storage_connection_uuid	string	No	—	Required unless resolved from media_profile_uuid / org default profile
bucket	string	No	—	Required unless resolved from media_profile_uuid / org default profile
key	string	No	—	Object key for the transcript; default <key_prefix>/transcript/<uuid>
language	string	No	—	ISO-639-1 hint (e.g. 'pt'); improves accuracy and latency
prompt	string	No	—	Optional biasing prompt — domain vocabulary, names, spellings
temperature	float	No	—	—
persist_transcript	boolean	No	—	Default true — write the transcript to storage as text/plain
register_artifact	boolean	No	—	Default true — index the transcript as a copy GeneratedArtifact
review_gate	string	No	—	—
brand	string	No	—	—
campaign	string	No	—	—
purpose	string	No	—	—
session_uuid	string	No	—	When set, also stamp agents.cost-entry-record unit=audio_second
produced_by_kind	string	No	—	—
produced_by_uuid	string	No	—	—
created_by_uuid	string	No	—	—

Output Schema

Field	Type	Required	Default	Description
workflow_run_id	string	No	—	Parent DAG workflow run id (engine-injected when used as a step)
organization_uuid	string	Yes	—	—
storage_object_uuid	string	Yes	—	StorageObject UUID of the audio to transcribe. Produce one with media.ingest.from-url (remote URL) or storage.upload.presigned-url (browser/direct upload).
media_profile_uuid	string	No	—	—
ai_provider_config_uuid	string	No	—	—
connection_uuid	string	No	—	Explicit AI CloudConnection UUID. Any connection serving the OpenAI /audio/transcriptions contract works; a non-native type can opt in with supports_transcription=true on its config.
model	string	No	—	—
storage_connection_uuid	string	No	—	Required unless resolved from media_profile_uuid / org default profile
bucket	string	No	—	Required unless resolved from media_profile_uuid / org default profile
key	string	No	—	Object key for the transcript; default <key_prefix>/transcript/<uuid>
language	string	No	—	—
prompt	string	No	—	Optional biasing prompt — domain vocabulary, names, spellings
temperature	float	No	—	—
persist_transcript	boolean	No	—	Default true — write the transcript to storage as text/plain
register_artifact	boolean	No	—	Default true — index the transcript as a copy GeneratedArtifact
review_gate	string	No	—	—
brand	string	No	—	—
campaign	string	No	—	—
purpose	string	No	—	—
session_uuid	string	No	—	When set, also stamp agents.cost-entry-record unit=audio_second
produced_by_kind	string	No	—	—
produced_by_uuid	string	No	—	—
created_by_uuid	string	No	—	—
transcript	string	No	—	Transcript text, truncated at 20000 chars
transcript_truncated	boolean	No	—	—
transcript_chars	integer	No	—	—
transcript_storage_object_uuid	string	No	—	Full transcript persisted as text/plain; always complete
audio_storage_object_uuid	string	No	—	—
audio_artifact_uuid	string	No	—	Existing GeneratedArtifact for the source audio, when indexed
artifact_uuid	string	No	—	GeneratedArtifact (kind=copy) indexing the transcript
duration_seconds	float	No	—	—
duration_source	string	No	—	provider
unit	string	No	—	—
quantity	float	No	—	—
cost_usd	string	No	—	—
provider	string	No	—	—
verdict	string	No	—	—
failure_reason	string	No	—	Engine-stamped human-readable failure reason
failed_at	string	No	—	ISO timestamp when the workflow failed
failed_at_state	string	No	—	Engine-stamped state when the workflow failed
failed_step	string	No	—	Engine-stamped step name (DAG path)
failed_layer	integer	No	—	Engine-stamped layer index (DAG path)
error	string	No	—	Engine-stamped exception message
error_type	string	No	—	Engine-stamped exception class name
completed_at	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

Outcomes

Outcome	Type	Description	State Data Keys
completed	SUCCESS	Media atom completed successfully	completed_at
failed	FAILURE	Media atom failed	failure_reason, error, error_type

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "media.audio.transcribe",
  "initial_data": {
    "organization_uuid": "value",
    "storage_object_uuid": "value"
  }
}