> ## 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.

# Seedance 2.5 Flash 동영상 생성

> 텍스트, 멀티모달 참조, 편집, 연장, 시작·끝 프레임으로 최대 30초의 480p / 720p 동영상을 생성합니다.

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2-5-flash",
  "prompt": "A cinematic shot of a fox walking through a sunlit forest, with a slow tracking camera",
  "resolution": "720p",
  "size": "16:9",
  "duration": 8,
  "generate_audio": true,
  "nsfw_check": true,
  "return_last_frame": true
}'
```

```python Python theme={null}
import requests

payload = {
  "model": "seedance-2-5-flash",
  "prompt": "A cinematic shot of a fox walking through a sunlit forest, with a slow tracking camera",
  "resolution": "720p",
  "size": "16:9",
  "duration": 8,
  "generate_audio": True,
  "nsfw_check": True,
  "return_last_frame": True
}
response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const payload = {
  "model": "seedance-2-5-flash",
  "prompt": "A cinematic shot of a fox walking through a sunlit forest, with a slow tracking camera",
  "resolution": "720p",
  "size": "16:9",
  "duration": 8,
  "generate_audio": true,
  "nsfw_check": true,
  "return_last_frame": true
};
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example_seedance25flash"
    }
  ]
}
```

`POST /v1/videos/generations`로 제출하고 `data[0].task_id`를 받은 뒤 `GET /v1/tasks/{task_id}`로 조회합니다.

**Authorization** `string` *required*

`Authorization: Bearer <token>`을 사용합니다. `<token>`은 APIMart API 키입니다.

## 요청 매개변수

**model** `string` *required*

`seedance-2-5-flash`를 사용합니다. `doubao-seedance-2-5-flash`도 허용합니다. 점이 포함된 `seedance-2.5-flash`는 지원하지 않습니다.

**nsfw\_check** `boolean` (default: false)

비디오 작업을 제출하기 전에 콘텐츠 검토를 실행할지 여부를 지정합니다.

* `true`: `omni-moderation-latest`로 프롬프트와 입력 이미지를 검토
* `false` 또는 생략: 검토 요청을 보내지 않으며 검토 비용이나 지연이 추가되지 않음(기본값)

차단 시 HTTP 400(`nsfw_content_detected`)을 반환하며 작업을 생성하거나 생성 요금을 부과하지 않습니다. 참조 동영상·오디오는 검토하지 않습니다. 검토 서비스 오류 시 요청이 계속 진행될 수 있습니다.

**prompt** `string` *required*

필수 프롬프트입니다. `@图片1` / `@视频1` / `@音频1`로 소재를 참조합니다. 번호는 1부터 시작하며 각 소재 배열의 순서에 대응합니다.

**resolution** `string` (default: 720p)

`480p` / `720p`만 지원하며 기본값은 `720p`입니다. `1080p`, `2k`, `4k` 등은 제출 시 HTTP 400을 반환합니다.

**size** `string` (default: adaptive)

`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`(기본값)를 지원합니다. 별칭은 `aspect_ratio`입니다. 시작·끝 프레임, 편집, 연장 작업은 `adaptive`만 가능합니다.

**duration** `integer`

정수 초 `4`–`30`; 일반 요청에서 생략하면 `5`, `-1`은 자동입니다. 명시적 `edit`는 `-1` 또는 생략만 허용하며, 생략 시 `-1`로 처리하고 원본 길이를 따릅니다. 자동 길이는 30초분을 선차감한 후 실제 토큰 사용량으로 정산합니다.

**generate\_audio** `boolean` (default: true)

출력 오디오 생성 여부로 기본값은 `true`이며 별칭은 `audio`입니다. 입력 참조 오디오인 `audio_urls`와 다릅니다.

**watermark** `boolean` (default: false)

AI 생성 워터마크 추가 여부로 기본값은 `false`입니다.

**seed** `integer`

선택적 난수 시드입니다. 같은 시드가 동일한 결과를 보장하지는 않습니다.

**output\_format** `string` (default: mp4)

출력 컨테이너는 `mp4`(기본값) 또는 `mov`입니다.

**omni\_reference\_task\_type** `string` (default: auto)

`auto`(기본값), `reference`, `edit`, `extend`를 지원하며 참조 소재가 있는 작업에만 사용합니다. 유형을 명시하면 제출 시 아래 제한을 검사합니다.

**image\_urls** `string[]`

모두 `reference_image`로 처리하는 참조 이미지 배열입니다. `image_with_roles`와 합쳐 최대 10장입니다. 시작·끝 프레임은 `image_with_roles`를 사용하세요.

**image\_with\_roles** `object[]`

각 항목에 `url`과 `role`이 필요합니다. 역할은 `reference_image`, `first_frame`(최대 1장), `last_frame`(최대 1장, 시작 프레임과 함께)입니다. `image_urls`와 합쳐 최대 10장이며 충돌하는 역할을 혼합하지 마세요. `video_urls` / `audio_urls`가 있으면 시작·끝 프레임은 멀티모달 참조 이미지로 처리됩니다.

**video\_urls** `string[]`

최대 5개, 각 2–30초, 합계 30초 이하입니다. 편집용 원본 동영상은 4–30초여야 합니다.

**audio\_urls** `string[]`

최대 5개, 각 2–30초, 합계 30초 이하입니다. 오디오만 참조할 수 있으며 이미지나 동영상이 필수는 아닙니다.

**return\_last\_frame** `boolean` (default: false)

`true`이면 성공 후 끝 프레임 이미지를 `data.result.videos[].last_frame_url`로 반환합니다.

**web\_search** `boolean` (default: false)

모델이 필요에 따라 웹을 검색하도록 허용합니다. 기본값은 `false`입니다.

**tools** `object[]`

선택적 도구 목록입니다. 웹 검색 예: `[{"type":"web_search"}]`.

> [!WARNING]
>
> `draft` / `draft_task_id`는 지원하지 않으므로 요청에서 제거하세요. 포함하면 제출 시 HTTP 400을 반환합니다. 초안 기능은 [Seedance 2.5](https://docs.apimart.ai/ko/api-reference/videos/seedance-2-5/generation.md)를 사용하세요.

## 소재 요구 사항

공개 접근 가능한 `http(s)` URL 또는 승인된 `asset://` ID를 사용합니다. 출력 해상도와 입력 동영상 픽셀 제한은 별도로 검사합니다.

| 소재 | 제한 |
| - | - |
| 이미지 | 두 이미지 필드 합계 ≤10장; JPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIF; 너비·높이 각각 300–6000 px; 비율 0.4–2.5; 각 `<30 MB`. |
| 동영상 | ≤5개; MP4 / MOV, 영상 H.264 / H.265, 오디오 AAC / MP3; 각 2–30초, 합계 ≤30초; 각 ≤200 MB; 너비·높이 각각 300–6000 px, 비율 0.4–2.5, 너비 × 높이 409,600–8,295,044픽셀, 24–60 FPS. |
| 오디오 | ≤5개; WAV / MP3; 각 2–30초, 합계 ≤30초; 각 ≤15 MB. |

## 작업 유형과 제한

| 모드 | 사용법과 제한 |
| - | - |
| 텍스트 → 동영상 | `prompt`를 제공하고 참조 소재와 `omni_reference_task_type`은 생략합니다. |
| 참조 → 동영상 | 참조 소재를 제공하며 `reference`는 선택 사항입니다. 일반 길이·비율 제한이 적용됩니다. |
| 시작·끝 프레임 | `image_with_roles`를 사용하며 `size` / `aspect_ratio`는 `adaptive`여야 합니다. |
| 동영상 편집 | `edit`; 4–30초 원본 동영상이 1개 이상 필요합니다. 비율은 `adaptive`, `duration`은 `-1` 또는 생략입니다. |
| 동영상 연장 | `extend`; 참조 동영상 1개 이상, 비율은 `adaptive`여야 합니다. |

명시한 유형의 제한을 위반하면 작업 생성·과금 전에 HTTP 400을 반환합니다. `auto`는 소재와 프롬프트로 유형을 판단하므로 생성 중에 제한 위반으로 실패할 수 있습니다. 명시적 유형도 프롬프트 의도와 다르면 `InvalidParameter.TaskTypeMismatch`가 발생할 수 있습니다.

## 요청 예제

### 멀티모달 참조

```json theme={null}
{
  "model": "seedance-2-5-flash",
  "prompt": "Use the composition of @视频1, the subject in @图片1, and @音频1 as background music",
  "image_urls": [
    "https://example.com/reference.jpg"
  ],
  "video_urls": [
    "https://example.com/reference_8s.mp4"
  ],
  "audio_urls": [
    "https://example.com/music_5s.mp3"
  ],
  "omni_reference_task_type": "reference",
  "duration": 8,
  "size": "16:9"
}
```

### 시작·끝 프레임

```json theme={null}
{
  "model": "seedance-2-5-flash",
  "prompt": "Smoothly transition from the first frame to the last frame",
  "image_with_roles": [
    {
      "url": "https://example.com/first.jpg",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/last.jpg",
      "role": "last_frame"
    }
  ],
  "size": "adaptive",
  "duration": 5
}
```

### 동영상 편집

```json theme={null}
{
  "model": "seedance-2-5-flash",
  "prompt": "Edit @视频1: replace the cloudy sky with a clear sunset while preserving the camera movement",
  "video_urls": [
    "https://example.com/source_10s.mp4"
  ],
  "omni_reference_task_type": "edit",
  "size": "adaptive",
  "duration": -1,
  "output_format": "mov"
}
```

### 동영상 연장

```json theme={null}
{
  "model": "seedance-2-5-flash",
  "prompt": "Extend @视频1 forward: continue the camera movement as the subject walks into the forest",
  "video_urls": [
    "https://example.com/source_10s.mp4"
  ],
  "omni_reference_task_type": "extend",
  "size": "adaptive",
  "duration": 5
}
```

## 비공개 소재 사용

실제 사람의 얼굴이 있는 이미지·동영상은 소재 라이브러리 승인 후 `asset://`로 사용하세요. 업로드 `model`도 `seedance-2-5-flash`로 설정합니다. [소재 라이브러리 API](https://docs.apimart.ai/ko/api-reference/videos/seedance-2-0/private-avatar.md)를 참고하고 아래 Flash 모델명을 사용하세요.

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/seedance2/private-avatar/assets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2-5-flash",
  "group": {
    "name": "flash-assets"
  },
  "asset_type": "Image",
  "assets": [
    {
      "url": "https://example.com/reference.jpg",
      "name": "reference"
    }
  ]
}'
```

통합 작업 API로 소재 검토를 조회합니다. 승인 후 소재 목록에서 `asset://` ID를 받아 `image_urls`, `image_with_roles[].url`, `video_urls`, `audio_urls`에 사용합니다.

## 작업 상태와 결과

[작업 조회 API](https://docs.apimart.ai/ko/api-reference/tasks/status.md)를 폴링합니다. `pending` / `processing`은 진행 중, `completed`는 성공, `failed`는 실패입니다. `data.result.videos[0].url[0]`을 읽으세요. `url`은 배열입니다.

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/tasks/task_example_seedance25flash' \
  --header 'Authorization: Bearer <token>'
```

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_seedance25flash",
    "status": "completed",
    "progress": 100,
    "cost": 0.3104,
    "credits_cost": 3.104,
    "usage": {
      "completion_tokens": 38800
    },
    "result": {
      "videos": [
        {
          "url": [
            "https://example.com/generated-video.mp4"
          ],
          "last_frame_url": "https://example.com/generated-last-frame.png"
        }
      ]
    }
  }
}
```

| 필드 | 의미 |
| - | - |
| `data.usage.completion_tokens` | 최종 정산 토큰 수. 완료 직후 몇 초 동안 없을 수 있으므로 다시 조회하세요. |
| `data.cost` | 계정 할인이 적용된 실제 청구액(USD). 반환값을 기준으로 합니다. |
| `data.credits_cost` | 실제 차감된 크레딧. |
| `data.result.videos[].url` | 동영상 URL 배열. 즉시 다운로드하여 저장하세요. |
| `data.result.videos[].last_frame_url` | `return_last_frame: true`로 요청하고 성공한 경우의 끝 프레임 URL. |
| `data.error.message` | 실패 이유. 실패 시 `data.cost`는 0이며 선차감액은 환불됩니다. |

## 요금 계산

* 제출 시 해상도별 초당 단가로 선차감합니다. 참조 동영상이 있으면 입력 포함 요금 구간을 사용하며 출력 길이와 참조 동영상 총길이를 합산합니다.
* 일반 요청의 `duration` 생략은 출력 5초, `duration: -1` 또는 `edit`의 길이 생략은 출력 30초를 기준으로 선차감합니다.
* 성공 후 `data.usage.completion_tokens` ÷ 1,000,000 × 해당 100만 토큰당 단가에 계정 할인을 적용하여 차액을 환불하거나 추가 차감합니다. 참조 동영상 유무에 따라 `token` / `token-input` 구간을 사용합니다. 최종 금액은 `data.cost`입니다.
* 제출 거절 시 생성 요금은 없고, 생성 실패 시 선차감액을 환불합니다. 단가와 할인은 [가격 페이지](https://apimart.ai/pricing)를 확인하세요.

## 일반적인 오류

| 상황 | 조치 |
| - | - |
| HTTP 400: 미지원 해상도 | `480p` / `720p`만 사용하고 `1080p`는 사용하지 마세요. |
| HTTP 400: 소재 수 초과 | 이미지 합계 10장, 동영상 5개, 오디오 5개 이내로 줄이고 길이도 확인하세요. |
| HTTP 400: 초안 미지원 | `draft` / `draft_task_id`를 제거합니다. |
| HTTP 400: 유형·길이·비율 오류 | `omni_reference_task_type`, `duration`, `size` / `aspect_ratio`의 조합을 확인하세요. |
| HTTP 400: `nsfw_content_detected` | 검토 거절로 처리하고 `error.message`에 따라 내용을 수정하세요. |
| 모델을 찾을 수 없음 | `seedance-2.5-flash`가 아닌 `seedance-2-5-flash`를 사용하세요. |
| 작업 `failed` | `data.error.message`를 확인하고 소재·프롬프트를 작업 유형에 맞추세요. 선차감액은 환불됩니다. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.