본문으로 건너뛰기
API 레퍼런스
API 레퍼런스

'Vidu' 영상 참조

최대 15개의 참조 이미지와 3개의 참조 오디오 클립으로 Vidu Q4 동영상을 생성합니다.

Markdown 보기
01

개요

지원되는 모델이 있는 비디오 엔드포인트에 대한 참조를 사용하세요. 반환된 작업 ID를 사용하여 해당 상태를 검색하거나 아래에 문서화된 전달에 'callback_url'를 제공하세요.

빠른 시작

  1. API 키를 만들고 RUNAPI_API_KEY로 설정합니다.
  2. 지원되는 모델을 선택하고 해당 모델의 스키마와 일치하는 본문으로 POST 요청을 전송합니다.
  3. 반환된 작업 ID를 저장한 후, 터미널 상태가 될 때까지 폴링하거나 아래에 문서화된 콜백을 처리하세요.

엔드포인트

POST /api/v1/vidu/reference_to_video
Base URL
https://runapi.ai
API 버전
v1
인증
Authorization: Bearer YOUR_API_TOKEN
02

지원 모델

현재 가격, 속도 제한 및 상업적 이용 세부 정보는 모델 페이지를 여십시오.

03

요청 스키마

JSON 본문

필드와 허용 값은 선택된 모델에 따라 다릅니다. 제공된 경우 callback_url은 아래에 문서화된 Task 전달을 수신합니다.

vidu-q4-reference-to-video필드 9개
aspect_ratiostring
선택

출력 비디오 종횡비.

허용 값: 16:9, 9:16, 1:1, 4:3, 3:4 기본값: 16:9
audioboolean
선택

동기화된 오디오를 생성합니다. False는 무음 비디오를 생성합니다.

기본값: true
callback_urlstring
선택

터미널 작업 결과에 대한RunAPI고객 콜백 URL입니다.

duration_secondsinteger
선택

비디오 재생 시간(초)입니다.

기본값: 5 범위: 3 - 16
modelstring
필수

'Vidu Q4' 비디오 참조 모델.

output_resolutionstring
선택

출력 비디오 해상도.

허용 값: 540p, 720p, 1080p, 2k, 4k 기본값: 720p
promptstring
필수

동영상 설명은 최대 20,000자입니다.

범위: 1 - 20000
reference_audio_urlsarray
선택

'MP3' 참조의 최대 3개의 'HTTP(S)' URL(각각 3~12초, 최대 50MB) 공급자는 원격 파일의 유효성을 검사합니다.

항목 제한: 3
reference_image_urlsarray
필수

1~15개의 'JPG', 'JPEG', 'PNG' 또는 'WEBP' 참조 이미지의 'HTTP(S)' URL을 주문했습니다. 공급자는 원격 파일의 유효성을 검사합니다.

항목 범위: 1 - 15
04

수락 만들기

HTTP 202

POST /api/v1/vidu/reference_to_video

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "processing"
}
05

폴링 처리 중

HTTP 200

GET /api/v1/vidu/reference_to_video/:id

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "processing"
}
06

폴링 완료

HTTP 200

GET /api/v1/vidu/reference_to_video/:id

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "usage": {
      "properties": {
        "cost": {
          "type": "number"
        }
      },
      "required": [
        "cost"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "videos": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "status",
    "videos",
    "usage"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "usage": {
    "cost": 0.05
  },
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
07

폴링 실패

HTTP 200

GET /api/v1/vidu/reference_to_video/:id

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}
08

고객 콜백: 완료됨

HTTP 200

POST callback_url

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "usage": {
      "properties": {
        "cost": {
          "type": "number"
        }
      },
      "required": [
        "cost"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "videos": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "status",
    "videos",
    "usage"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "usage": {
    "cost": 0.05
  },
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
09

고객 콜백: 실패함

HTTP 200

POST callback_url

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}
10

오류

HTTP 401

POST /api/v1/vidu/reference_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Authentication required"
}
11

오류

HTTP 401

GET /api/v1/vidu/reference_to_video/:id

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Authentication required"
}
12

오류

HTTP 400

POST /api/v1/vidu/reference_to_video

응답 스키마
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "사람이 읽을 수 있는 오류 메시지.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "사람이 읽을 수 있는 유효성 검사 요약입니다.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "공개 요청 필드를 키로 하는 유효성 검사 메시지로, 각 필드에 대해 사람이 읽을 수 있는 문자열 배열이 포함됩니다.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

응답 예시

JSON 
{
  "error": "model must be one of: vidu-q4-reference-to-video"
}
13

오류

HTTP 402

POST /api/v1/vidu/reference_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Insufficient balance"
}
14

오류

HTTP 429

POST /api/v1/vidu/reference_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "API key credit limit exceeded"
}
15

오류

HTTP 409

POST /api/v1/vidu/reference_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
16

오류

HTTP 429

POST /api/v1/vidu/reference_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
17

오류

HTTP 503

POST /api/v1/vidu/reference_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Service under maintenance, please try again later"
}
18

오류

HTTP 504

POST /api/v1/vidu/reference_to_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "The request timed out"
}
19

오류

HTTP 404

GET /api/v1/vidu/reference_to_video/:id

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
20

생성된 코드 샘플

cURL을 직접 사용하거나 해당 언어의 SDK를 설치하세요. 각 샘플은 이 레퍼런스에 표시된 유효성 검사된 요청을 제출합니다.

설치

Shell 
pip install runapi-vidu
PYTHON 
import os
from runapi.vidu import ViduClient

client = ViduClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.reference_to_video.create(
  model="vidu-q4-reference-to-video",
  prompt="The reference character walks through a quiet city.",
  reference_image_urls=["https://file.runapi.ai/reference.png"],
  duration_seconds=5,
  output_resolution="720p",
  audio=True,
  aspect_ratio="16:9"
)