동영상 모델고급 사용자업데이트
POST/v1/videos/generations
viduq3
요청 ID viduq3
프로토콜
POST /v1/videos/generations· 영상 생성 예시GET /v1/videos/tasks/{id}· 영상 작업 조회 예시GET /v1/videos/tasks/{id}/content· 영상 다운로드 예시DELETE /v1/videos/tasks/{id}· 완료된 영상 작업 삭제 예시POST /v1/videos/assets· 소재 업로드 예시DELETE /v1/videos/assets/{id}· 소재 삭제 예시
인증
요청에는 API 키 관리의 API 키가 필요합니다. JSON 요청은 Content-Type: application/json을 지정하세요.
Authorization: Bearer YOUR_API_KEY
요청 매개변수
POST /v1/videos/generations
| 필드 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
model | string | 필수 | viduq3. 이 페이지에 표시된 모델 ID를 사용하세요. |
prompt | string | 조건부 | 장면, 동작, 카메라 움직임을 설명합니다. 텍스트 지시가 필요하면 이 필드나 type: "text"인 content 항목을 사용합니다. 최대 5000자입니다. |
content | array<object> | 필수 | 필수 참조 미디어 목록입니다. 이미지는 최대 7장입니다. |
content[].type | string | 필수 | 사용 가능한 값은 text, image_url, input_image입니다. |
content[].text | string | 조건부 | type: "text"인 항목에 프롬프트를 지정하세요. |
content[].role | string | 조건부 | 일반 참조 이미지에는 reference_image를 사용합니다. 일반 참조 이미지의 역할은 생략할 수 있습니다. |
content[].asset_id | string | 조건부 | POST /v1/videos/assets에 소재를 업로드하고 반환된 id를 사용합니다. multipart에서 kind(image)를 file보다 먼저 보냅니다. |
resolution | string | 선택 | 사용 가능한 값은 540p, 720p, 1080p입니다. 기본값은 720p입니다. |
ratio | string | 선택 | 출력 화면 비율입니다. aspect_ratio도 사용할 수 있습니다. 사용 가능한 값은 1:1, 9:16, 16:9, 3:4, 4:3입니다. 기본값은 16:9입니다. |
duration | integer | 선택 | 출력 길이이며 단위는 초입니다. 3~16초 범위의 정수입니다. 기본값은 5입니다. |
generation_mode | string | 선택 | 사용 가능한 값은 auto, r2v입니다. 기본값 auto는 입력에 맞는 모드를 선택합니다. 명시적 모드는 입력과 일치해야 합니다. |
요청 예시
API Key를 로컬 환경 변수 ICODEEASY_API_KEY에 설정하고 직접 HTTP 호출을 허용하는 엔드포인트를 선택하세요. 특정 클라이언트가 필요한 경우 해당 설정 가이드를 따르세요.
예시의 미디어 URL 및 에셋 ID를 유효한 내 에셋으로 바꾸세요.
Video Generations
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/generations' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"model": "viduq3",
"prompt": "Move the camera slowly toward the subject in the reference image.",
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"content": [
{
"type": "image_url",
"role": "reference_image",
"asset_id": "YOUR_IMAGE_ASSET_ID"
}
]
}'
영상 작업 조회
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY"
영상 다운로드
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID/content' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-L \
-o result.mp4
완료된 영상 작업 삭제
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-i \
-X DELETE
소재 업로드
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/assets' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-F 'kind=image' \
-F '[email protected];type=image/png'
소재 삭제
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/assets/YOUR_ASSET_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-i \
-X DELETE
응답 및 작업
HTTP 202 · 작업 접수
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "viduq3",
"created_at": "2026-07-30T08:00:00Z",
"status_url": "/v1/videos/tasks/vid_1785398400000000000",
"content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
"status": "queued",
"updated_at": "2026-07-30T08:00:00Z",
"task_id": "vid_1785398400000000000"
}
HTTP 200 · 완료 작업 조회
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "viduq3",
"created_at": "2026-07-30T08:00:00Z",
"status_url": "/v1/videos/tasks/vid_1785398400000000000",
"content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
"status": "succeeded",
"updated_at": "2026-07-30T08:01:00Z",
"url": "/v1/videos/tasks/vid_1785398400000000000/content"
}
id를 저장하세요. 같은 API 키로 status_url에 GET 요청을 보내 status가 succeeded 또는 failed가 될 때까지 확인하세요. 성공한 뒤 content_url에서 내려받고 HTTP 리디렉션을 따르세요. 두 경로는 API 기본 URL에 대한 상대 경로입니다.
| 필드 | 유형 | 설명 |
|---|---|---|
id / task_id | string | 작업 ID입니다. 생성 응답의 task_id는 id와 같습니다. |
status | string | 작업 상태이며 queued, running, succeeded 또는 failed입니다. |
progress | integer | 생성 진행률입니다. 진행률 값이 없으면 생략됩니다. |
error.code | string | 작업 실패 시 반환되는 오류 분류입니다. |
주요 오류
| HTTP | 오류 유형 | 설명 |
|---|---|---|
| 400 | invalid_request | 모델, 매개변수 조합, 참조 미디어를 확인하세요. |
| 401 | unauthorized | API 키가 누락되었거나 유효하지 않거나 비활성화되었는지 확인하세요. |
| 402 | insufficient_balance | 작업 제출에 필요한 잔액이 부족합니다. |
| 404 | not_found | 조회 결과가 404이면 작업 ID를 보관하고 조회 URL과 작업을 만든 계정의 API 키를 확인하세요. 작업이 이미 완료되었을 수 있으니 이 응답만으로 다시 제출하지 마세요. |
| 409 | video_not_ready | 영상이 아직 생성 중입니다. 상태 조회를 계속하세요. |
| 503 | submission_unknown | 제출 결과를 확인할 수 없습니다. 새 요청을 보내기 전에 지원팀에 작업 생성 여부를 확인하세요. |
전체 연동 가이드 · 요청 필드, 작업 상태 및 응답 형식은 전체 API 가이드를 참고하세요.
기능 및 제한
text_to_video· 미지원image_to_video· 지원first_frame· 미지원last_frame· 미지원reference_images· 지원video_input· 미지원audio· 공개되지 않음- 제한 해상도: 540p, 720p, 1080p · 화면 비율: 1:1, 9:16, 16:9, 3:4, 4:3 · 참조 이미지: 최대 7개 · 길이: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 · 입력: Site images ≤10 MB. No audio reference upload. No supplier task IDs.