imagetovideo

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 3, 2026 License: MIT Imports: 10 Imported by: 0

README

Image to Video AI Go

Go Reference Test

An idiomatic Go client for AI Image to Video. Create image-to-video generation tasks, poll their status, and retrieve completed video URLs.

Install

go get github.com/waeckerlinfederowicz66-sketch/imagetovideo-go

Create an API key from settings/apikeys/create, then keep it outside source control:

export IMAGETOVIDEO_API_KEY="your_api_key"

Create a video

package main

import (
    "context"
    "fmt"
    "os"
    "time"

    imagetovideo "github.com/waeckerlinfederowicz66-sketch/imagetovideo-go"
)

func main() {
    client, err := imagetovideo.NewClient(os.Getenv("IMAGETOVIDEO_API_KEY"))
    if err != nil {
        panic(err)
    }

    created, err := client.CreateVideo(context.Background(), imagetovideo.CreateRequest{
        Source:      imagetovideo.ImageSource{"https://example.com/source.jpg"},
        Prompt:      "A slow camera push-in with soft natural movement",
        Duration:    5,
        Model:       "seedance-1.5-pro",
        AspectRatio: "16:9",
    })
    if err != nil {
        panic(err)
    }

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
    defer cancel()

    result, err := client.Wait(ctx, created.TaskID)
    if err != nil {
        panic(err)
    }
    if result.Status != imagetovideo.StatusSuccess {
        panic("generation did not succeed")
    }
    fmt.Println(result.URL)
}

First and last frames

Use TailImageURL when the selected model supports an ending frame:

created, err := client.CreateVideo(ctx, imagetovideo.CreateRequest{
    Source:       imagetovideo.ImageSource{"https://example.com/start.jpg"},
    TailImageURL: "https://example.com/end.jpg",
    Prompt:       "Transition smoothly from the first composition to the last",
    Duration:     5,
    Model:        "seedance-1.5-pro",
})

Multiple source images

ImageSource encodes one URL as a string and multiple URLs as an array:

Source: imagetovideo.ImageSource{
    "https://example.com/reference-1.jpg",
    "https://example.com/reference-2.jpg",
}

Model capabilities vary. Check that the selected model supports multiple references, a final frame, audio, the requested duration, resolution, and aspect ratio.

Error handling

API failures are returned as *imagetovideo.APIError, including the application error code and HTTP status.

var apiErr *imagetovideo.APIError
if errors.As(err, &apiErr) {
    log.Printf("request rejected: %s", apiErr.Message)
}

Security

  • Never commit API keys.
  • Load IMAGETOVIDEO_API_KEY from an environment variable or secret manager.
  • The client sends the key only in the Authorization: Bearer header.
  • Tests use local mock servers and contain no credentials.

License

MIT

Documentation

Overview

Package imagetovideo provides a small Go client for creating and polling Image to Video AI generation tasks.

Index

Examples

Constants

View Source
const (
	StatusPending    = "pending"
	StatusProcessing = "processing"
	StatusSuccess    = "success"
	StatusFailed     = "failed"
	StatusCanceled   = "canceled"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	StatusCode int
	Code       int
	Message    string
}

APIError is returned when the service rejects a request.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client calls the Image to Video AI API.

func NewClient

func NewClient(apiKey string, options ...Option) (*Client, error)

NewClient creates an API client. The API key is sent only as a Bearer token.

func (*Client) CreateVideo

func (c *Client) CreateVideo(ctx context.Context, request CreateRequest) (*CreateResponse, error)

CreateVideo starts an image-to-video generation task.

Example
package main

import (
	"context"
	"fmt"
	"os"

	imagetovideo "github.com/waeckerlinfederowicz66-sketch/imagetovideo-go"
)

func main() {
	client, err := imagetovideo.NewClient(os.Getenv("IMAGETOVIDEO_API_KEY"))
	if err != nil {
		panic(err)
	}

	task, err := client.CreateVideo(context.Background(), imagetovideo.CreateRequest{
		Source:      imagetovideo.ImageSource{"https://example.com/source.jpg"},
		Prompt:      "A slow camera push-in with soft natural movement",
		Duration:    5,
		Model:       "seedance-1.5-pro",
		AspectRatio: "16:9",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(task.TaskID)
}

func (*Client) GetTask

func (c *Client) GetTask(ctx context.Context, taskID string) (*Task, error)

GetTask returns the current state of a generation task.

func (*Client) Wait

func (c *Client) Wait(ctx context.Context, taskID string) (*Task, error)

Wait polls a generation task until it succeeds, fails, is canceled, or the context is canceled.

Example
package main

import (
	"context"
	"fmt"
	"os"
	"time"

	imagetovideo "github.com/waeckerlinfederowicz66-sketch/imagetovideo-go"
)

func main() {
	client, err := imagetovideo.NewClient(os.Getenv("IMAGETOVIDEO_API_KEY"))
	if err != nil {
		panic(err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
	defer cancel()

	result, err := client.Wait(ctx, "task-id")
	if err != nil {
		panic(err)
	}
	if result.Status == imagetovideo.StatusSuccess {
		fmt.Println(result.URL)
	}
}

type CreateRequest

type CreateRequest struct {
	Source        ImageSource `json:"url"`
	Prompt        string      `json:"prompt,omitempty"`
	Duration      int         `json:"duration"`
	Model         string      `json:"model"`
	Resolution    string      `json:"resolution,omitempty"`
	AspectRatio   string      `json:"aspectRatio,omitempty"`
	AudioURL      string      `json:"audioUrl,omitempty"`
	GenerateAudio *bool       `json:"generateAudio,omitempty"`
	TailImageURL  string      `json:"tailImageUrl,omitempty"`
}

CreateRequest describes an image-to-video generation request.

type CreateResponse

type CreateResponse struct {
	TaskID    string `json:"taskId"`
	RequestID string `json:"requestId"`
	Status    string `json:"status"`
}

CreateResponse identifies a newly-created generation task.

type ImageSource

type ImageSource []string

ImageSource holds one or more public source-image URLs. A single URL is encoded as a JSON string, while multiple URLs are encoded as an array.

func (ImageSource) MarshalJSON

func (source ImageSource) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type Option

type Option func(*Client) error

Option customizes a Client.

func WithBaseURL

func WithBaseURL(rawURL string) Option

WithBaseURL replaces the default API base URL. It is primarily useful for tests.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient replaces the default HTTP client.

func WithPollInterval

func WithPollInterval(interval time.Duration) Option

WithPollInterval sets the interval used by Wait.

type Task

type Task struct {
	TaskID string    `json:"taskId"`
	Status string    `json:"status"`
	URL    string    `json:"url,omitempty"`
	Videos []Video   `json:"videos,omitempty"`
	Result *TaskInfo `json:"result,omitempty"`
}

Task describes the current state and output of a generation task.

func (Task) Done

func (task Task) Done() bool

Done reports whether the task has reached a terminal state.

type TaskInfo

type TaskInfo struct {
	Videos       []Video `json:"videos,omitempty"`
	Status       string  `json:"status,omitempty"`
	ErrorCode    string  `json:"errorCode,omitempty"`
	ErrorMessage string  `json:"errorMessage,omitempty"`
}

TaskInfo contains provider result details.

type Video

type Video struct {
	VideoURL     string  `json:"videoUrl"`
	ThumbnailURL string  `json:"thumbnailUrl,omitempty"`
	Duration     float64 `json:"duration,omitempty"`
}

Video describes a generated video result.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL