# Seedance 2.5 - Core.Today AI API

> ByteDance's flagship multimodal video model with native audio, native 30-second single-pass generation, and large multimodal reference sets (up to 30 images, 10 videos, 10 audios). Supports text-to-video, image-to-video, first/last-frame control, video editing, extension, and lip-sync.

- **Provider**: ByteDance
- **Model ID**: bytedance/seedance-2.5
- **Category**: Video Generation
- **Credits**: 5500 per 5s 720p video — billed per second (480p 513/s, 720p 1100/s, 1080p 1335/s); with reference videos, billed per measured (input+output) second: 480p 308, 720p 660, 1080p 799 credits/s
- **Speed**: Medium
- **Quality**: Ultra

## Features
- Native 30-second generation in a single pass — no stitching between clips
- Audio and video generated together, so dialogue, sound effects, and music are synchronized from the start
- Large reference sets: up to 30 images, 10 videos, and 10 audio files, addressed in the prompt as [Image1], [Video1], [Audio1]
- Video editing and extension from a reference clip while preserving the original motion and camera work
- Character consistency across shots when reference images are supplied

## Use Cases
- Single-take 30-second product or brand films with synchronized voice-over
- Dialogue scenes where the spoken lines are written in double quotes and lip-synced automatically
- Outfit-change and product-showcase videos driven by reference images plus a motion reference video
- Editing an existing clip — replacing an object or background while keeping the original camera move
- Extending an existing shot with consistent characters, environment, and style

## API Endpoint

Base URL: https://api.core.today/v1
Create Prediction: POST /predictions
Get Status: GET /predictions/{job_id}

## Authentication
Header: X-API-Key: YOUR_API_KEY

## Input Parameters

### Required
- **duration**: integer - Video duration in seconds (4-30). Required — upstream also accepts -1 for intelligent duration, but the resulting length is unknown at request time and cannot be billed accurately, so this gateway requires an explicit duration.

### Optional
- **prompt**: string - Text prompt for video generation. Maximum 20000 characters (BytePlus states no hard cap; quality is best under ~1,000 English words). Optional when a media input (image, reference images/videos/audios) is supplied.
- **resolution**: string (default: 720p) - Video resolution. 1080p is billed at a higher per-second rate.
  Options: 480p, 720p, 1080p
- **image**: string - First-frame image for image-to-video or first/last-frame generation. Cannot be combined with reference images, videos, or audios.
- **last_frame_image**: string - Last-frame image. Requires a first-frame image. Cannot be combined with reference images, videos, or audios.
- **reference_images**: array - Reference images (up to 30) for character consistency, style guidance, and scene composition. Cannot be combined with first/last frame images. Reference them in your prompt as [Image1], [Image2], etc.
- **reference_videos**: array - Reference videos (up to 10, combined duration max 30s) for motion transfer, style reference, editing, and extension. Supplying any reference video switches billing to the higher video_in rate.
- **reference_audios**: array - Reference audio files (up to 10, combined duration max 30s) for audio-driven generation and lip-sync. Requires at least one reference image or video.
- **aspect_ratio**: string (default: adaptive) - Video aspect ratio. 'adaptive' (default) lets the model choose the best ratio based on inputs. First/last-frame, editing, and extension modes require 'adaptive'.
  Options: adaptive, 16:9, 4:3, 1:1, 3:4, 9:16, 21:9
- **generate_audio**: boolean (default: true) - Generate synchronized audio with the video, including dialogue (use double quotes in prompt), sound effects, and background music.
- **watermark**: boolean (default: false) - Add a watermark to the generated video.
- **output_format**: string (default: mp4) - Output video container format.
  Options: mp4, mov
- **seed**: integer - Random seed. Set for reproducible generation. Reproducibility is not guaranteed.

## Examples

### Text to video with native audio
A 5-second 720p clip generated from a prompt alone, with synchronized ambience produced in the same pass.
```json
{
  "model": "bytedance/seedance-2.5",
  "input": {
    "prompt": "a golden retriever puppy running across a green meadow toward the camera, slow motion, warm afternoon light",
    "duration": 5,
    "resolution": "720p",
    "seed": 42
  }
}
```

### Multimodal reference — character from an image, motion from a video
Combine reference images and a reference video, then describe how to merge them by addressing each input in the prompt.
```json
{
  "model": "bytedance/seedance-2.5",
  "input": {
    "prompt": "The character from [Image1] performs the dance from [Video1] on a neon-lit stage.",
    "reference_images": [
      "https://example.com/character.jpg"
    ],
    "reference_videos": [
      "https://example.com/dance-reference.mp4"
    ],
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "adaptive"
  }
}
```

## Response Format
```json
{
  "job_id": "abc123",
  "status": "pending | processing | completed | failed",
  "result": "URL or data (when completed)"
}
```

## Usage Flow
1. POST /predictions with model and input -> receive job_id
2. GET /predictions/{job_id} -> poll until status is completed or failed
3. Result contains output URL(s)

## Tips
- Realistic-person references (even AI-generated faces) are rejected by the provider's real-person filter. Register the image first with POST /v1/assets, wait for status active, then pass asset://<asset_id> in reference_images or image. Registration is charged once; output can still be rejected by output moderation, which is refunded.
- Be specific about camera movement, lighting, and mood — the model follows detailed direction well.
- For dialogue, put the spoken words in double quotes: The man stopped and said: "Remember this moment." The model generates matching lip movement and voice.
- Start at 5 seconds while iterating on style, then raise duration once you are happy with the look — billing is per second of output.
- Reference videos switch billing to the video_in rate, which is roughly 4x the base rate. Use reference images alone when motion transfer is not needed.
- First/last-frame, editing, and extension modes require aspect_ratio: 'adaptive'.

## Documentation
https://docs.byteplus.com/en/docs/ModelArk/2607688