Media Library

List, poll, and manage your generated images, videos, music, and 3D assets in one place.

The Media Library is a unified record of media-generation jobs across all asset types — images, videos, music, and 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.

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.

The media generation record

A media generation has the following fields:

Prop

Type

List generations

GET /v1/media/generations

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).

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

Response

{
  "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

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)

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

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.

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

Poll until complete

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

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

POST /v1/media/generations

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

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.

The generation endpoints under images, video, music, and 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.

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.

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 /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.

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

The media generation record

A media generation has the following fields:

Prop

Type

List generations

GET /v1/media/generations

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).

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

Response

{
  "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

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)

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

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.

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

Poll until complete

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

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

POST /v1/media/generations

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

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.

Update a generation record

PATCH /v1/media/generations/{generation_id}

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 /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.

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

The media generation record

List generations

Query parameters

Response

Type-specific listings

Retrieve one generation

Poll until complete

Create a generation record

Parameters

Update a generation record

Delete a generation record

On this page

Media Library

The media generation record

List generations

Query parameters

Response

Type-specific listings

Retrieve one generation

Poll until complete

Create a generation record

Parameters

Update a generation record

Delete a generation record

On this page