> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List Videos
> List the current principal's videos — character+motion Renders and H3 text-to-video generations — with cursor pagination.
Returns the authenticated principal's own videos, newest `created_at` first, through opaque cursor pagination. A video is either a character+motion Render (`render_` prefix, created with [Render Video (from Character and/or Motion)](/v1/api-reference/renders/create)) or a MiniMax H3 text-to-video generation (`vid_` prefix, created with [Generate Video (from Text)](/v1/api-reference/videos/create-from-text), [First Frame](/v1/api-reference/videos/create-from-first-frame), or [First-Last Frames](/v1/api-reference/videos/create-from-first-last-frame)); the two sources are merged into one list by `created_at`. This endpoint replaces the retired `GET /v1/renders`.
`GET /v1/renders` no longer accepts `GET` — it now answers `405 Method Not Allowed`, not `404`, because `POST /v1/renders` is still registered on the same path. If your integration checked for a `404` to detect that the old route was gone, accept `405` too, or switch straight to this endpoint.
## Request parameters
| Parameter | Type | Required | Default | Description |
| --------- | ------- | :------: | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | string | No | — | Optional exact lifecycle filter: `queued`, `processing`, `ready`, `failed`, or `cancelled`. Omit it to include videos in every status. |
| `cursor` | string | No | — | Opaque continuation token from the previous response's `next_cursor`. Pass it unchanged and keep the same filters while paging; maximum length is 512 characters. |
| `limit` | integer | No | `20` | Maximum video summaries returned in one page. Accepts 1–100; use `next_cursor` rather than calculating an offset for later pages. |
## Response parameters
Returns `200 OK`.
| Field | Type | Always present | Description |
| ---------------------- | --------------- | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items` | array | Yes | One page of video summaries, newest first, mixing Render- and H3-sourced items. |
| `items[].id` | string | Yes | `render_...` for a character+motion Render, or `vid_...` for an H3 generation. |
| `items[].status` | string | Yes | `queued`, `processing`, `ready`, `failed`, or `cancelled`. |
| `items[].stage` | string or null | Yes | Populated only for a Render-sourced item while `status` is `processing`. `null` in every other case — including a Render in `ready`/`queued`/`failed`/`cancelled`, and every H3 item regardless of status. This is intentional, not a gap in the data. |
| `items[].progress` | integer or null | Yes | Progress from 0 to 100, or `null`. |
| `items[].created_at` | string or null | Yes | Render-sourced timestamps carry nanosecond precision; H3-sourced timestamps carry second precision. Two items created within the same second can look out of order if you diff the raw strings — the list order itself is correct, only the printed precision differs between the two sources. |
| `items[].completed_at` | string or null | Yes | See **Completion timing** below. |
A video summary deliberately carries no signed media URL and no failure detail — fetch [Get Video](/v1/api-reference/videos/get) for the full state.
```json theme={null}
{
"items": [
{"id":"render_a1b2c3","status":"ready","stage":null,"progress":100,"created_at":"2026-08-25T09:12:03.123456789Z","completed_at":"2026-08-25T09:13:47Z"},
{"id":"vid_3f2a9c","status":"ready","stage":null,"progress":100,"created_at":"2026-08-24T09:12:03Z","completed_at":"2026-08-24T09:13:47Z"}
],
"next_cursor": null,
"has_more": false
}
```
## Completion timing
On a Render-sourced item, `completed_at` can lag `status` reaching `ready` by up to roughly 30 seconds before it backfills — it isn't a permanent gap. Decide whether a video is finished by checking `status == "ready"`, not by whether `completed_at` is non-null.
## Examples
```bash cURL theme={null}
curl "https://apis.viggle.ai/v1/videos?status=ready&limit=20" -H "Authorization: Bearer $VIGGLE_API_KEY"
```
```python Python theme={null}
import os, requests
response = requests.get("https://apis.viggle.ai/v1/videos", params={"status": "ready", "limit": 20}, headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"})
response.raise_for_status()
page = response.json()
```
```javascript JavaScript theme={null}
const response = await fetch("https://apis.viggle.ai/v1/videos?status=ready&limit=20", { headers: { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` } });
const page = await response.json();
```
```go Go theme={null}
req, _ := http.NewRequest("GET", "https://apis.viggle.ai/v1/videos?status=ready&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
```
To page through results, pass the previous response's `next_cursor` as `cursor` on the next request; stop once `has_more` is `false`.
## Next step
Use [Get Video](/v1/api-reference/videos/get) on any `items[].id` for the full state, including `video_url`.
## OpenAPI
````yaml openapi.yaml GET /v1/videos
openapi: 3.0.3
info:
title: Viggle API
description: Generate AI-powered character animation videos
version: 2.0.0
contact:
name: Viggle Support
url: https://viggle.ai
servers:
- url: https://apis.viggle.ai
description: Production server
security:
- bearerAuth: []
tags:
- name: Renders
description: Prepare inputs, create renders, observe progress, and retrieve results.
- name: Credits
description: Read the credit balance available to the calling principal.
- name: Characters
description: |
Create, list, inspect, and delete reusable character assets. `type`
selects whether creation also extracts a 3D vsplat; export its
download URL separately once ready.
- name: Motions
description: |
Create, list, inspect, and delete reusable motion assets, and import one
from an official motion template. `type` selects whether creation also
extracts or generates a 3D animation; export its download URL
separately once ready.
- name: Videos
description: |
Generate a MiniMax H3 text-to-video (`vid_` prefix), and read the
unified view over every video the caller owns — H3 generations and
character+motion Renders (`render_` prefix) — merged into one
resource.
paths:
/v1/videos:
get:
tags:
- Videos
summary: List the current principal's videos
description: |
Returns the authenticated principal's own videos, newest `created_at`
first, through opaque cursor pagination. A video is either a
character+motion Render (`render_` prefix) or a MiniMax H3
text-to-video generation (`vid_` prefix); both sources are merged
into one feed by `created_at`. This endpoint replaces the retired
`GET /v1/renders`.
operationId: listVideos
parameters:
- name: status
in: query
required: false
description: >-
Optional lifecycle filter. When supplied, the page contains only
videos whose current status exactly matches this value.
schema:
$ref: '#/components/schemas/ResourceStatus'
- name: cursor
in: query
required: false
description: >-
Opaque continuation token from the previous page's `next_cursor`.
Pass it unchanged and keep all other filters consistent while
paging.
schema:
type: string
minLength: 1
maxLength: 512
- name: limit
in: query
required: false
description: >-
Maximum number of video summaries to return in one page, from 1
through 100. The default is 20.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/SourceChannel'
responses:
'200':
description: One page of the principal's videos.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/VideoPage'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/V1Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
components:
schemas:
ResourceStatus:
description: |
The public lifecycle shared by every asynchronous resource. It carries
the same values as `RenderStatus`.
type: string
enum:
- queued
- processing
- ready
- failed
- cancelled
VideoPage:
type: object
additionalProperties: false
required:
- items
- next_cursor
- has_more
properties:
items:
type: array
description: |
Video summaries in reverse chronological order for this page,
merging Render-sourced and H3-sourced videos owned by the caller
into one feed.
items:
$ref: '#/components/schemas/VideoSummary'
next_cursor:
type: string
description: >-
Opaque cursor for the next page; null when there is no later page.
Pass it unchanged as the next `cursor` query value.
nullable: true
has_more:
type: boolean
description: Whether another page is available after the current one.
VideoSummary:
type: object
description: |
List projection of a Video — the unified resource for a finished
character+motion Render (`render_` prefix) and a MiniMax H3
text-to-video generation (`vid_` prefix). It deliberately carries no
signed media URL and no failure detail: fetch
`GET /v1/videos/{video_id}` for the full state.
`stage` is populated only when the item is Render-sourced and
`status` is `processing`; it is null in every other case, including
every H3 item regardless of status. `created_at` carries nanosecond
precision on Render-sourced items and second precision on H3 items —
compare timestamp values, not string precision, when two items were
created within the same second.
additionalProperties: false
required:
- id
- status
- stage
- progress
- created_at
- completed_at
properties:
id:
type: string
description: >-
Public video ID — a Render (`render_` prefix) or an H3 generation
(`vid_` prefix).
minLength: 1
status:
description: >-
Current lifecycle state; `ready`, `failed`, and `cancelled` are
terminal.
allOf:
- $ref: '#/components/schemas/ResourceStatus'
stage:
type: string
description: >-
Coarse pipeline phase. Populated only for a Render-sourced item
while `status` is `processing`; null otherwise, and always null for
an H3 item.
nullable: true
allOf:
- $ref: '#/components/schemas/RenderStage'
progress:
type: integer
description: >-
Best-effort completion percentage from 0 through 100; null when the
source pipeline reports no estimate.
nullable: true
minimum: 0
maximum: 100
created_at:
type: string
description: >-
Creation timestamp. Render-sourced items report nanosecond
precision; H3 items report second precision.
nullable: true
format: date-time
completed_at:
type: string
description: |
Terminal-state timestamp; null while the video is still active.
On a Render-sourced item this can lag `status` reaching `ready`
by up to roughly 30 seconds before it is backfilled — use
`status`, not the presence of this field, to detect completion.
nullable: true
format: date-time
ErrorResponse:
type: object
additionalProperties: false
required:
- error
properties:
error:
description: >-
Top-level draft-flow error payload containing the stable code,
message, retry guidance, correlation ID, and error-specific details.
allOf:
- $ref: '#/components/schemas/ErrorBody'
RenderStage:
description: |
A coarse progress hint. `analyzing`, `rendering`, and `finishing` are
emitted for renders created through the `multipart/form-data` form;
every other value belongs to the draft-based pipeline. Treat an
unrecognized value as "in progress" rather than failing.
type: string
enum:
- queued
- preparing
- generating
- finalizing
- ready
- failed
- cancelled
- analyzing
- rendering
- finishing
ErrorBody:
type: object
additionalProperties: false
required:
- code
- message
- retryable
- request_id
- details
- remediation
properties:
code:
description: Stable error category from the draft-based render error vocabulary.
allOf:
- $ref: '#/components/schemas/ErrorCode'
message:
type: string
description: >-
Human-readable explanation suitable for logs or presentation to a
developer.
retryable:
type: boolean
description: >-
Whether retrying the operation without changing its semantic input
may succeed.
request_id:
type: string
description: >-
Correlation identifier for tracing and support. Include it when
reporting the failure.
details:
type: object
description: Error-specific structured context; available keys depend on `code`.
additionalProperties: true
remediation:
description: Suggested recovery action and optional retry delay.
allOf:
- $ref: '#/components/schemas/ErrorRemediation'
ErrorCode:
description: |
The failure vocabulary of the draft-based render flow. The resource
operations project the same vocabulary onto the lower_snake_case codes
described by `ResourceError`.
type: string
enum:
- UNAUTHENTICATED
- INVALID_CREDENTIAL
- FORBIDDEN
- INVALID_REQUEST
- INVALID_CHARACTER
- INVALID_MOTION
- UNSUPPORTED_MEDIA
- CONTENT_POLICY_VIOLATION
- UPLOAD_REQUIRED
- UPLOAD_MISMATCH
- UPLOAD_EXPIRED
- DRAFT_NOT_FOUND
- DRAFT_ALREADY_CONSUMED
- RENDER_NOT_FOUND
- RENDER_NOT_CANCELLABLE
- CHARACTER_NOT_FOUND
- MOTION_NOT_FOUND
- MOTION_NOT_READY
- MOTION_TEMPLATE_NOT_FOUND
- AVATAR_NOT_FOUND
- ANIMATION_NOT_FOUND
- EXTRACTION_UNAVAILABLE
- EXTRACTION_FAILED
- IDEMPOTENCY_KEY_REUSED
- INSUFFICIENT_CREDITS
- RATE_LIMITED
- SERVICE_BUSY
- INTERNAL_ERROR
ErrorRemediation:
type: object
additionalProperties: false
required:
- action
- retry_after_ms
properties:
action:
type: string
description: >-
Suggested machine-readable or human-readable next action, such as
retrying later, uploading media again, or correcting input.
retry_after_ms:
type: integer
description: >-
Recommended delay in milliseconds before retrying; null when no
timed retry is advised.
nullable: true
format: int64
minimum: 0
parameters:
RequestId:
name: X-Request-Id
in: header
required: false
description: >-
Optional caller-supplied correlation ID, up to 128 characters. The
service returns the effective value in the response header for tracing
and support.
schema:
type: string
minLength: 1
maxLength: 128
SourceChannel:
name: X-Viggle-Source
in: header
required: false
description: >-
Optional source-channel label, up to 128 characters, used to attribute
traffic to an SDK, integration, product surface, or internal workflow.
schema:
type: string
minLength: 1
maxLength: 128
headers:
RequestId:
description: Stable request identifier for support and tracing.
schema:
type: string
responses:
BadRequest:
description: Invalid request.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
V1Unauthorized:
description: Missing, invalid, or expired credential.
headers:
WWW-Authenticate:
schema:
type: string
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: Credential does not grant access to this resource.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
RateLimited:
description: Rate limit exceeded.
headers:
Retry-After:
schema:
type: integer
minimum: 0
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: Unexpected server error.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ServiceUnavailable:
description: Service temporarily unavailable.
headers:
Retry-After:
schema:
type: integer
minimum: 0
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key or OAuth access token
description: |
Server-side SDK clients use a project API key. Remote MCP clients use
an OAuth access token. Never expose a project API key in browser code.
````