# Media Library (/docs/media-library)


The Media Library is a unified record of media-generation jobs across all asset types —
[images](/docs/images), [videos](/docs/video), [music](/docs/music), and [3D](/docs/3d). Each record
tracks a generation's status, parameters, result URLs, and metadata, so you can list past
generations, poll an in-flight job to completion, and clean up records.

<Callout type="info">
  These endpoints are authenticated with a **dashboard session** (the same login used by the web
  Dashboard), not an `sk-` API key. The library tracks generations created through Yunxin; the actual
  media files are stored by the providers. Records expire automatically after 30 days.
</Callout>

## The media generation record [#the-media-generation-record]

A media generation has the following fields:

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, description: &#x22;Unique generation id (UUID).&#x22; },
  media_type: { type: &#x22;string&#x22;, description: &#x22;One of image, video, music, threed.&#x22; },
  status: { type: &#x22;string&#x22;, description: &#x22;One of pending, processing, completed, failed.&#x22; },
  model: { type: &#x22;string&#x22;, description: &#x22;Model used for generation.&#x22; },
  prompt: { type: &#x22;string | null&#x22;, description: &#x22;Input prompt.&#x22; },
  parameters: { type: &#x22;object&#x22;, description: &#x22;Generation parameters (size, quality, duration, etc.).&#x22; },
  result_urls: { type: &#x22;string[]&#x22;, description: &#x22;All result URLs (may be empty until completed).&#x22; },
  primary_url: { type: &#x22;string | null&#x22;, description: &#x22;Primary result URL.&#x22; },
  preview_url: { type: &#x22;string | null&#x22;, description: &#x22;Preview/thumbnail URL.&#x22; },
  file_size_bytes: { type: &#x22;number | null&#x22;, description: &#x22;File size in bytes.&#x22; },
  duration_seconds: { type: &#x22;number | null&#x22;, description: &#x22;Duration for video/music.&#x22; },
  width: { type: &#x22;number | null&#x22;, description: &#x22;Width for image/video.&#x22; },
  height: { type: &#x22;number | null&#x22;, description: &#x22;Height for image/video.&#x22; },
  error: { type: &#x22;string | null&#x22;, description: &#x22;Error message if the generation failed.&#x22; },
  created_at: { type: &#x22;number&#x22;, description: &#x22;Unix timestamp (seconds) when created.&#x22; },
  completed_at: { type: &#x22;number | null&#x22;, description: &#x22;Unix timestamp (seconds) when completed/failed.&#x22; },
}"
/>

## List generations [#list-generations]

```
GET /v1/media/generations
```

### Query parameters [#query-parameters]

| Parameter    | Type    | Default | Description                                                       |
| ------------ | ------- | ------- | ----------------------------------------------------------------- |
| `media_type` | string  | —       | Filter by type: `image`, `video`, `music`, `threed`.              |
| `status`     | string  | —       | Filter by status: `pending`, `processing`, `completed`, `failed`. |
| `page`       | integer | `1`     | Page number (≥ 1).                                                |
| `page_size`  | integer | `20`    | Items per page (1–100).                                           |

```bash
curl "https://api.yuhuanstudio.com/v1/media/generations?media_type=image&page_size=20" \
  -H "Authorization: Bearer $YUNXIN_SESSION_TOKEN"
```

### Response [#response]

```json
{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "media_type": "image",
      "status": "completed",
      "model": "model-id",
      "prompt": "A watercolor fox",
      "parameters": { "size": "1024x1024" },
      "result_urls": ["https://.../image.png"],
      "primary_url": "https://.../image.png",
      "preview_url": null,
      "file_size_bytes": 482000,
      "duration_seconds": null,
      "width": 1024,
      "height": 1024,
      "error": null,
      "created_at": 1709251200,
      "completed_at": 1709251260
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "has_more": false
}
```

## Type-specific listings [#type-specific-listings]

Convenience endpoints return the same list shape, pre-filtered to a single media type. Each accepts
`page` and `page_size`.

| Endpoint               | Media type    |
| ---------------------- | ------------- |
| `GET /v1/media/images` | `image`       |
| `GET /v1/media/videos` | `video`       |
| `GET /v1/media/music`  | `music`       |
| `GET /v1/media/threed` | `threed` (3D) |

```bash
curl "https://api.yuhuanstudio.com/v1/media/videos?page=1&page_size=10" \
  -H "Authorization: Bearer $YUNXIN_SESSION_TOKEN"
```

## Retrieve one generation [#retrieve-one-generation]

```
GET /v1/media/generations/{generation_id}
```

Returns a single media generation record. Returns `404` if the id doesn't exist or doesn't belong to
you.

```bash
curl "https://api.yuhuanstudio.com/v1/media/generations/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer $YUNXIN_SESSION_TOKEN"
```

### Poll until complete [#poll-until-complete]

Many [video](/docs/video), [music](/docs/music), and [3D](/docs/3d) generations are asynchronous.
Poll the record until `status` is `completed` (or `failed`), then read `primary_url` / `result_urls`.

```python
import os
import time
import requests

BASE = "https://api.yuhuanstudio.com/v1"
headers = {"Authorization": f"Bearer {os.environ['YUNXIN_SESSION_TOKEN']}"}
gen_id = "f47ac10b-58cc-4372-a567-0e02b2c3d479"

while True:
    record = requests.get(f"{BASE}/media/generations/{gen_id}", headers=headers).json()
    if record["status"] in ("completed", "failed"):
        break
    time.sleep(3)

if record["status"] == "completed":
    print("Result:", record["primary_url"])
else:
    print("Failed:", record["error"])
```

## Create a generation record [#create-a-generation-record]

```
POST /v1/media/generations
```

Creates a record to track a generation. Returns `201` with the new record (initial `status` is
`pending`).

### Parameters [#parameters]

| Parameter          | Type   | Required | Description                                 |
| ------------------ | ------ | -------- | ------------------------------------------- |
| `media_type`       | string | Yes      | One of `image`, `video`, `music`, `threed`. |
| `model`            | string | Yes      | Model used for generation.                  |
| `prompt`           | string | No       | Input prompt.                               |
| `provider_task_id` | string | No       | Provider task id for async polling.         |
| `parameters`       | object | No       | Generation parameters.                      |

<Callout type="info">
  The generation endpoints under [images](/docs/images), [video](/docs/video), [music](/docs/music),
  and [3d](/docs/3d) are what actually produce assets. Creating a record here is for tracking a job in
  the library and is typically handled for you by the Dashboard.
</Callout>

## Update a generation record [#update-a-generation-record]

```
PATCH /v1/media/generations/{generation_id}
```

Updates fields on a record — most often `status` and the result fields once a provider job
finishes. Setting `status` to `completed` or `failed` stamps `completed_at`. Updatable fields:
`status`, `provider_task_id`, `result_urls`, `primary_url`, `preview_url`, `file_size_bytes`,
`duration_seconds`, `width`, `height`, `input_tokens`, `output_tokens`, `cost_credits`, `error`.

```bash
curl -X PATCH \
  "https://api.yuhuanstudio.com/v1/media/generations/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer $YUNXIN_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed", "primary_url": "https://.../image.png"}'
```

## Delete a generation record [#delete-a-generation-record]

```
DELETE /v1/media/generations/{generation_id}
```

Removes the record from your library. This deletes only the database record, not the underlying media
file. Returns `204 No Content` on success.

```bash
curl -X DELETE \
  "https://api.yuhuanstudio.com/v1/media/generations/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer $YUNXIN_SESSION_TOKEN"
```

## Related topics [#related-topics]

* [Image Generation](/docs/images)
* [Video Generation](/docs/video)
* [Music Generation](/docs/music)
* [3D Generation](/docs/3d)