# Image-to-Video Quick Start Guide

This guide demonstrates how to use the SkyReels SDK's image-to-video generation feature.

## Features

- Generate videos from a starting image and text prompt
- Async/await support with tokio
- Customizable duration, sound, and quality modes
- Task submission and status polling
- Comprehensive error handling

## API Endpoints

- **Submit**: `POST /api/v1/video/image2video/submit`
- **Query**: `GET /api/v1/video/image2video/task/{task_id}`

## Parameters

### Required Parameters

- `api_key`: Your SkyReels API key
- `prompt`: Text description of the video to generate (max: 1280 tokens)
- `first_frame_image`: URL of the starting image (supports: jpg/jpeg, png, gif, bmp)

### Optional Parameters

- `duration`: Video duration in seconds (default: 5, range: 3-15)
- `sound`: Whether to include sound effects (default: false)
- `mode`: Quality/performance mode (default: "std", supports: "fast", "std", "pro")

## Quick Example

```rust,no_run
use skyreels::{Mode, SkyReelsClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client
    let client = SkyReelsClient::new("your_api_key");

    // Create request
    let request = client
        .image2video()
        .submit_request(
            "Camera slowly pans across the scene",
            "https://example.com/image.jpg"
        )
        .duration(5)
        .sound(true)
        .mode(Mode::Std)
        .build();

    // Submit task
    let task_id = client.image2video().submit(request).await?;

    // Wait for completion
    let result = client
        .image2video()
        .wait_for_completion(&task_id, 5, 120)
        .await?;

    if let Some(video) = result.get_video_data() {
        println!("Video ready: {}", video.video_url);
    }

    Ok(())
}
```

## Running the Example

1. Set your API key as an environment variable:
   ```bash
   export SKYREELS_API_KEY="your_api_key_here"
   ```

2. Run the example:
   ```bash
   cargo run --example image2video_example
   ```

## Response Structure

### Submit Response
```json
{
  "task_id": "string",
  "msg": "string",
  "code": 200,
  "status": "ok",
  "data": null,
  "trace_id": "string"
}
```

### Task Response (Success)
```json
{
  "task_id": "string",
  "msg": "string",
  "code": 200,
  "status": "success",
  "data": {
    "video_url": "string",
    "duration": 5,
    "resolution": "1920x1080"
  },
  "trace_id": "string"
}
```

## Task Status

- `submitted`: Task has been submitted
- `pending`: Task is waiting in queue
- `running`: Task is being processed
- `success`: Task completed successfully
- `failed`: Task failed
- `unknown`: Unknown status

## Tips

1. **Image URL**: Ensure your image is publicly accessible via URL
2. **Duration**: Videos can be 3-15 seconds long
3. **Prompt**: Be descriptive about the camera movements and scene changes
4. **Polling**: Use `wait_for_completion()` for automatic polling
5. **Sound**: Enable sound for better video experience

## Error Handling

The SDK provides comprehensive error handling:

```rust,no_run
match client.image2video().submit(request).await {
    Ok(task_id) => {
        println!("Task submitted: {}", task_id);
    }
    Err(e) => {
        eprintln!("Failed to submit task: {}", e);
        // Handle specific error types
        match e {
            skyreels::Error::SubmissionFailed(msg) => {
                eprintln!("Submission failed: {}", msg);
            }
            skyreels::Error::RateLimited => {
                eprintln!("Rate limited, please retry later");
            }
            _ => {
                eprintln!("Other error: {}", e);
            }
        }
    }
}
```

## API Documentation

For more detailed API information, see:
- Full API docs: [docs/prd/image-to-video.md](../docs/prd/image-to-video.md)
- Rust docs: Run `cargo doc --open`
