列出视频
curl --request GET \
--url https://apis.viggle.ai/v1/videos \
--header 'Authorization: Bearer <token>'import requests
url = "https://apis.viggle.ai/v1/videos"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://apis.viggle.ai/v1/videos', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://apis.viggle.ai/v1/videos",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://apis.viggle.ai/v1/videos"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://apis.viggle.ai/v1/videos")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://apis.viggle.ai/v1/videos")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"status": "queued",
"stage": "queued",
"progress": 50,
"created_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}
],
"next_cursor": "<string>",
"has_more": true
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}视频
列出视频
使用游标分页列出当前调用者的渲染、H3 视频和角色动画。
GET
/
v1
/
videos
列出视频
curl --request GET \
--url https://apis.viggle.ai/v1/videos \
--header 'Authorization: Bearer <token>'import requests
url = "https://apis.viggle.ai/v1/videos"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://apis.viggle.ai/v1/videos', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://apis.viggle.ai/v1/videos",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://apis.viggle.ai/v1/videos"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://apis.viggle.ai/v1/videos")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://apis.viggle.ai/v1/videos")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"status": "queued",
"stage": "queued",
"progress": 50,
"created_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}
],
"next_cursor": "<string>",
"has_more": true
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"details": {},
"remediation": {
"action": "<string>",
"retry_after_ms": 1
}
}
}通过不透明游标分页返回当前身份拥有的视频,按
摘要不包含签名媒体 URL 或失败详情;完整状态请调用获取视频。
继续分页时,将上一次响应中的
created_at 从新到旧排列。列表合并三种来源:通过渲染视频创建的 render_;通过文本、首帧、首尾帧或参考素材生成的 H3 vid_;以及使用 Viggle-Animate生成的 anim_。本接口替代已停用的 GET /v1/renders。
GET /v1/renders 现返回 405 Method Not Allowed,而不是 404,因为同一路径仍支持 POST /v1/renders。如旧集成通过 404 判断接口已停用,请同时处理 405,或直接迁移到本接口。请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
status | string | 否 | — | 精确状态筛选:queued、processing、ready、failed 或 cancelled。省略时包含全部状态。 |
cursor | string | 否 | — | 上一次响应的 next_cursor,请原样传入,并保持分页筛选条件一致。最长 512 字符。 |
limit | integer | 否 | 20 | 每页最多返回的视频摘要数量,范围 1–100。后续页使用 next_cursor,不要自行计算偏移量。 |
响应参数
返回200 OK。
| 字段 | 类型 | 始终返回 | 说明 |
|---|---|---|---|
items | array | 是 | 一页视频摘要,按创建时间从新到旧排列,混合 Render、H3 和角色动画三种来源。 |
items[].id | string | 是 | Render 为 render_...,H3 为 vid_...,角色动画为 anim_...。 |
items[].status | string | 是 | queued、processing、ready、failed 或 cancelled。 |
items[].stage | string 或 null | 是 | 仅 Render 来源且 status=processing 时有值。Render 的其他状态,以及所有 H3 和角色动画条目,均为 null,这是预期行为。 |
items[].progress | integer 或 null | 是 | 0–100 的进度,或 null。 |
items[].created_at | string 或 null | 是 | Render 精确到纳秒,H3 和角色动画精确到秒。同一秒创建的条目若直接比较字符串,可能看似乱序;列表本身顺序正确,仅显示精度不同。 |
items[].completed_at | string 或 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"},
{"id":"anim_7c1e4b","status":"ready","stage":null,"progress":100,"created_at":"2026-09-09T09:12:03Z","completed_at":"2026-09-09T09:13:47Z"}
],
"next_cursor": null,
"has_more": false
}
完成时间
Render 来源的视频在status 变为 ready 后,completed_at 可能延迟约 30 秒回填,并非永久缺失。判断完成状态时应检查 status == "ready",不要依赖 completed_at 非空。
示例
curl "https://apis.viggle.ai/v1/videos?status=ready&limit=20" -H "Authorization: Bearer $VIGGLE_API_KEY"
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()
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();
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()
next_cursor 作为下一次请求的 cursor。当 has_more 为 false 时停止。
下一步
使用任意items[].id 调用获取视频,获取包括 video_url 在内的完整状态。授权
服务端 SDK 使用项目 API 密钥,Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。
请求头
可选的调用者自定义关联 ID,最长 128 字符。服务会在响应头返回实际使用的值,便于追踪和支持排查。
Required string length:
1 - 128可选来源标签,最长 128 字符,用于识别 SDK、集成、产品入口或内部工作流。
Required string length:
1 - 128查询参数
可选生命周期筛选。提供后仅返回当前状态与该值完全匹配的视频。 异步资源共用的公开生命周期,枚举值与 RenderStatus 相同。
可用选项:
queued, processing, ready, failed, cancelled 上一页 next_cursor 返回的不透明令牌,请原样传入,分页时保持其他筛选条件一致。
Required string length:
1 - 512每页最多视频摘要数量,范围 1–100,默认 20。
必填范围:
1 <= x <= 100
