# Media generation

Media runs as asynchronous jobs: submit, poll, download. Output is copied
into private platform cache storage when the job finishes (kept at most 12 hours
from job creation and never backed up), so it does not
expire with the provider.

## Endpoints

| Endpoint | Produces |
| --- | --- |
| `POST https://api.openmayhem.ai/v1/images/generations` | Images |
| `POST https://api.openmayhem.ai/v1/videos` | Video |
| `POST https://api.openmayhem.ai/v1/audio/speech` | Speech audio |
| `POST https://api.openmayhem.ai/v1/audio/transcriptions` | Text from uploaded audio |
| `POST https://api.openmayhem.ai/v1/audio/generations` | Generated audio |
| `POST https://api.openmayhem.ai/v1/music/generations` | Music |
| `POST https://api.openmayhem.ai/v1/workflows` | Whatever the workflow graph produces |

<a id="media-settings"></a>

## Presets, dimensions and repeatability

A preset supplies compatible generation settings. Steps, guidance, sampler, duration and batch count are available only where supported. A larger batch produces more outputs and can increase both cost and capacity requirements.

Custom size means a supported width and height, not unlimited resolution. Dimensions must satisfy the model’s allowed increments, aspect-ratio rules and total pixel limit, as well as an available provider’s limits. Start from a valid preset when a custom combination is rejected.

For comparisons, keep the model, prompt, seed and settings fixed and change one control at a time. A fixed seed helps repeat experiments; it does not guarantee identical faces or identical output across providers or model updates.

<a id="styles-and-loras"></a>

## Styles and approved LoRAs

A LoRA adapts a model toward a style, subject or other learned behavior. When LoRA controls are available, choose from the workflow’s approved catalog, set the strength, and retain the same selection and order for comparisons. Supported counts and strength ranges depend on the workflow.

When a selected LoRA has trigger words, Studio adds them to the generated prompt automatically. Direct workflow API requests must include the catalog trigger in the positive prompt. Start with one LoRA and adjust its strength before combining several. LoRAs can change a face or composition as well as the intended style.

Reference uploads do not install LoRA weights. Arbitrary LoRA files and graph nodes are not accepted through these controls. Advanced JSON must still satisfy the same approved model, parts and workflow contract.

<a id="reference-inputs"></a>

## Reference inputs

Use a workflow that explicitly supports the reference you need, such as image editing or image-to-video. Attach the required files and select their offered roles. An upload alone does not add reference support to a text-only workflow or guarantee character identity.

For API workflows, input_files carries named, base64-encoded files. Graph file references must match those filenames. Follow the selected contract’s accepted formats, sizes and required inputs.

<a id="workflow-api"></a>

## Discover and submit a workflow

Use the public catalog to choose an endpoint first. GET /v1/models/by-id?id=… returns model details; URL-encode the id. Inspect endpoints, request_contracts, workflow, workflow_media and live_capacity_profiles where present. Approved presets, parts and live capacity determine which combinations can run.

For a WORKFLOWS model, configure a valid request in Studio and inspect its generated JSON. Save the complete request body, including model, workflow and any input_files, as workflow-request.json. Submit it with an API key that allows WORKFLOWS. The JSON must include file contents, not local browser file paths.

LoRAs belong in the approved workflow graph; there is no universal loras field to add to every image endpoint. Keep the generated model and graph together. After submission, use the job lifecycle below to poll and download the result.

```bash
curl "https://api.openmayhem.ai/v1/models?endpoint_family=WORKFLOWS&live=true"

MODEL_ID='replace-with-a-catalog-model-id'
curl --get "https://api.openmayhem.ai/v1/models/by-id" \
  --data-urlencode "id=$MODEL_ID"
```

```bash
curl https://api.openmayhem.ai/v1/workflows \
  -H "Authorization: Bearer $OPENMAYHEM_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @workflow-request.json
```

- [Your first media generation](https://openmayhem.ai/docs/studio#first-media-generation)
- [Media estimates and credit holds](https://openmayhem.ai/docs/billing#media-estimates)
- [When a media request cannot run](https://openmayhem.ai/docs/errors#media-troubleshooting)

## Job lifecycle

Submitting returns a job with a `polling_url`. Poll
`GET https://api.openmayhem.ai/v1/jobs/{id}` until `status` is `completed`, `failed` or
`cancelled`; the completed job carries the cost and artifact list.
`DELETE https://api.openmayhem.ai/v1/jobs/{id}` cancels a running job (work already done is
still billed). `GET https://api.openmayhem.ai/v1/jobs` lists recent jobs.

Artifacts download from `GET https://api.openmayhem.ai/v1/artifacts/{id}` with the same bearer
key, via a short-lived signed URL.

Request parameters are validated against the model's signed contract; a
missing required attribute fails with 400 `contract_attribute_required`
before any credit is reserved.