> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# FLUX 3 비디오 생성
> - 비동기 처리 모드, 후속 조회를 위한 작업 ID 반환
- 통합 진입점: 텍스트-비디오 / 이미지-비디오 / 비디오 이어쓰기 / 드래프트 2단계
- 출력 H.264 + AAC, 동기 오디오 포함, 길이 5~20초
- 해상도 hd / fhd, 7가지 종횡비
```bash cURL theme={null}
curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"model": "flux-3-video",
"prompt": "An orange cat jumps onto a sunlit wooden table, its tail brushes a glass that wobbles but does not fall. Cinematic, shallow depth of field.",
"duration": 5,
"resolution": "hd",
"aspect_ratio": "16:9"
}'
```
```python Python theme={null}
import requests
url = "https://api.apimart.ai/v1/videos/generations"
payload = {
"model": "flux-3-video",
"prompt": "An orange cat jumps onto a sunlit wooden table, its tail brushes a glass that wobbles but does not fall. Cinematic, shallow depth of field.",
"duration": 5,
"resolution": "hd",
"aspect_ratio": "16:9",
}
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json",
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript JavaScript theme={null}
const url = "https://api.apimart.ai/v1/videos/generations";
const payload = {
model: "flux-3-video",
prompt: "An orange cat jumps onto a sunlit wooden table, its tail brushes a glass that wobbles but does not fall. Cinematic, shallow depth of field.",
duration: 5,
resolution: "hd",
aspect_ratio: "16:9",
};
const headers = {
Authorization: "Bearer ",
"Content-Type": "application/json",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
```
```go Go theme={null}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
url := "https://api.apimart.ai/v1/videos/generations"
payload := map[string]interface{}{
"model": "flux-3-video",
"prompt": "An orange cat jumps onto a sunlit wooden table",
"duration": 5,
"resolution": "hd",
"aspect_ratio": "16:9",
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer ")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
```json 200 theme={null}
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
}
]
}
```
```json 400 theme={null}
{
"error": {
"code": 400,
"message": "잘못된 요청 매개변수입니다",
"type": "invalid_request_error"
}
}
```
```json 401 theme={null}
{
"error": {
"code": 401,
"message": "인증에 실패했습니다. API 키를 확인해주세요",
"type": "authentication_error"
}
}
```
```json 402 theme={null}
{
"error": {
"code": 402,
"message": "잔액이 부족합니다. 충전 후 다시 시도해주세요",
"type": "payment_required"
}
}
```
```json 422 theme={null}
{
"error": {
"code": 422,
"message": "매개변수 충돌 또는 잘못된 값입니다",
"type": "invalid_request_error"
}
}
```
```json 429 theme={null}
{
"error": {
"code": 429,
"message": "요청이 너무 많습니다. 잠시 후 다시 시도해주세요",
"type": "rate_limit_error"
}
}
```
## 인증
모든 엔드포인트는 Bearer Token 인증이 필요합니다
[API Key 관리 페이지](https://apimart.ai/keys)에서 API Key를 받으세요:
```
Authorization: Bearer YOUR_API_KEY
```
## 생성 모드
`flux-3-video`는 **통합 진입점**입니다. 필드로 모드를 추론하거나 `mode`로 명시할 수 있습니다.
| 모드 | 트리거 | 설명 |
| ------------------ | ------------------------------------ | --------------------------------- |
| **텍스트-비디오 (t2v)** | `prompt`만 | 순수 텍스트 |
| **이미지-비디오 (i2v)** | `image_urls` | 키프레임, 아래 참조 |
| **비디오 이어쓰기 (v2v)** | `video_url` / `video_urls` | 단가 더 높음, 이미지와 비디오가 모두 있으면 이어쓰기 우선 |
| **드래프트 → 최종** | `draft:true` 또는 `draft_from_task_id` | 저가 미리보기 후 정가 최종본 |
`mode` 값: `t2v` / `i2v` / `v2v` / `draft_enhance`, 또는 공식 표기 `text-to-video` / `image-continuation` / `video-continuation`. **명시 `mode`가 최우선**입니다.
### 이미지-비디오 키프레임 의미
`image_urls`의 순서가 의미입니다 — 정렬하거나 중복 제거하지 마세요:
| 장수 | 의미 |
| ----- | ---------------------------------------------------- |
| 1 | **시작 프레임** |
| 2 | 첫 장이 시작, 둘째 장이 **끝 프레임** |
| 3\~10 | 첫 장 시작, 마지막 장 끝, 중간 프레임 **균등 배치** (`duration` 명시 권장) |
## 요청 매개변수
고정 값: `flux-3-video`
프롬프트. `draft_from_task_id` 사용 시 **전송 금지** (전송 시 거부됨).
길이(초), 정수 **5\~20**, 기본값 `5`
**`duration: "auto"`는 미지원**입니다(과금에 고정 초 필요). 생략, `"auto"`, 비정수 → 오류 없이 **5초**로 처리하며 자동 적응하지 않습니다.
**비디오 이어쓰기** 시 실제 출력이 요청 초보다 짧을 수 있습니다(예: 5초 요청 → 4초). 요청 초로 선차감 후 완료 시 차액을 환불합니다. 최종 금액은 조회의 `cost` 기준입니다. 텍스트/이미지-비디오에서는 이 차이가 없습니다.
해상도
* `hd` (기본값, `720p`도 허용)
* `fhd` (`1080p`도 허용)
실측: `hd`는 16:9에서 약 1280×704, `fhd`는 약 1920×1088.
드래프트 모드(`draft:true`)는 **`hd`만** 허용.
종횡비
옵션: `21:9`, `2:1`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, 또는 `auto` (기본값, 프롬프트와 소재로 자동 선택)
이미지-비디오 키프레임, **1\~10**, 공개 http(s) URL 또는 base64
이어쓰기용 입력 비디오 (mp4, 공개 URL 또는 base64)
`video_url`과 동일, **첫 번째** 항목 사용 (호환)
동기 오디오 생성, 기본값 `true`. `false`는 무음 비디오 (**할인 없음**)
드래프트 모드: 약 **1/3 가격** 저품질 미리보기, `resolution: hd`만
드래프트 → 최종: **본인**의 성공한 드래프트 작업 ID
* `resolution`만 변경 가능, 프롬프트·길이·이미지·비디오는 변경 불가
* 최종본 정가 과금, 드래프트 비용은 상쇄되지 않음
* `draft:true`와 **상호 배타**
모더레이션 허용도 **0\~4**, 기본값 `2` (클수록 관대)
FLUX.2 이미지(0~~5) 또는 Kontext(0~~6)와 혼동하지 마세요.
명시 모드(선택), 생성 모드 참조
## 드래프트 모드
반복 비용이 클 때의 2단계 워크플로:
```
Step 1 draft:true → 약 1/3 가격 저품질 미리보기
Step 2 draft_from_task_id → 드래프트 룩에 맞춘 정가 최종본
```
### 드래프트 생성
```json theme={null}
{
"model": "flux-3-video",
"prompt": "An orange cat jumps onto a sunlit wooden table",
"duration": 5,
"draft": true
}
```
### 드래프트에서 최종본
```json theme={null}
{
"model": "flux-3-video",
"draft_from_task_id": "task_01K_DRAFT...",
"resolution": "fhd"
}
```
드래프트에서 최종본으로 전환할 때, 드래프트에 저장된 파라미터(모드 / 프롬프트 / 시드 / 소재)로 풀 퀄리티 렌더링합니다. 이어쓰기 드래프트의 최종본은 이어쓰기 최종 단가로 과금됩니다.
## 요청 예시
### 텍스트-비디오 (세로)
```json theme={null}
{
"model": "flux-3-video",
"prompt": "Rainy Tokyo street at night, neon in puddles, a person walks with an umbrella.",
"duration": 8,
"resolution": "fhd",
"aspect_ratio": "9:16"
}
```
### 이미지-비디오 (시작 + 끝 프레임)
```json theme={null}
{
"model": "flux-3-video",
"prompt": "Slow push-in as a flower opens from bud to bloom",
"image_urls": [
"https://example.com/bud.jpg",
"https://example.com/bloom.jpg"
],
"duration": 5
}
```
### 비디오 이어쓰기
```json theme={null}
{
"model": "flux-3-video",
"prompt": "Camera keeps following as the lead turns toward a distant lighthouse",
"video_url": "https://example.com/clip.mp4",
"duration": 5
}
```
### 무음 비디오
```json theme={null}
{
"model": "flux-3-video",
"prompt": "...",
"audio": false
}
```
## 제약
| 제한 | 값 |
| ------------------ | ------------------------------- |
| 길이 | 정수 5\~20 (`auto` 미지원, `21`은 거부) |
| 키프레임 | 1\~10 |
| 해상도 | `hd` / `fhd`만, 드래프트는 `hd`만 |
| 종횡비 | 7가지 또는 `auto` |
| `safety_tolerance` | 0\~4 |
### 흔한 제출 오류 (보통 미과금)
| 경우 | 설명 |
| ---------------------------------------------- | ---------------- |
| `prompt` 누락 | 드래프트 최종화 제외 필수 |
| 잘못된 `resolution` / `aspect_ratio` / `duration` | 범위 밖 |
| 키프레임 > 10 | 상한 초과 |
| 명시 `i2v`에 이미지 없음 / `v2v`에 비디오 없음 | 모드/소재 불일치 |
| `draft:true` + `fhd` | 드래프트는 hd만 |
| 무효 / 비드래프트 / 미완료 `draft_from_task_id` | 최종화 전제 조건 |
| 최종화 시 prompt / duration 변경 | `resolution`만 허용 |
| `draft`와 `draft_from_task_id` 동시 | 상호 배타 |
모더레이션 실패는 `failed`로 종료되며 **전액 환불**됩니다.
## 기능 커버리지
| 기능 | 상태 |
| --------------------- | --------------------------------- |
| t2v / i2v / v2v | ✅ 자동 또는 명시 `mode` |
| 드래프트 / 드래프트 최종화 | ✅ `draft` / `draft_from_task_id` |
| 동기 오디오 | ✅ 기본 켜짐, `audio:false`로 끔 (할인 없음) |
| 시간 지정 키프레임 `[초, 이미지]` | ❌ 균등 배치 키프레임 배열만 |
| `duration: "auto"` | ❌ 미지원 |
## Response
상태 코드, 성공 시 200
응답 데이터 배열
작업 상태, 생성 시 `submitted`
폴링용 작업 ID
**결과 조회**
비디오 생성은 비동기입니다. [작업 상태 조회](/ko/api-reference/tasks/status)로 폴링하세요.
권장 간격 **5\~10초**, 클라이언트 타임아웃 **15분** (20초 fhd는 더 느림). 실측 `t2v` + `hd` + 5초 약 60초.
성공 시 `result.videos[0].url` 사용. 결과물은 플랫폼 CDN에 미러됩니다. `cost`가 최종 청구액입니다. 실패 시 전액 환불.