Video API workflow

curl --request POST \
  --url https://api.freemodel.app/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "prompt": "<string>",
  "seconds": "<string>",
  "size": "<string>",
  "aspect_ratio": "<string>",
  "image_urls": [
    "<string>"
  ],
  "video_url": "<string>",
  "webhook": "<string>"
}
'

import requests

url = "https://api.freemodel.app/v1/videos"

payload = {
    "model": "<string>",
    "prompt": "<string>",
    "seconds": "<string>",
    "size": "<string>",
    "aspect_ratio": "<string>",
    "image_urls": ["<string>"],
    "video_url": "<string>",
    "webhook": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    prompt: '<string>',
    seconds: '<string>',
    size: '<string>',
    aspect_ratio: '<string>',
    image_urls: ['<string>'],
    video_url: '<string>',
    webhook: '<string>'
  })
};

fetch('https://api.freemodel.app/v1/videos', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.freemodel.app/v1/videos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'prompt' => '<string>',
    'seconds' => '<string>',
    'size' => '<string>',
    'aspect_ratio' => '<string>',
    'image_urls' => [
        '<string>'
    ],
    'video_url' => '<string>',
    'webhook' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.freemodel.app/v1/videos"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"seconds\": \"<string>\",\n  \"size\": \"<string>\",\n  \"aspect_ratio\": \"<string>\",\n  \"image_urls\": [\n    \"<string>\"\n  ],\n  \"video_url\": \"<string>\",\n  \"webhook\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.freemodel.app/v1/videos")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"seconds\": \"<string>\",\n  \"size\": \"<string>\",\n  \"aspect_ratio\": \"<string>\",\n  \"image_urls\": [\n    \"<string>\"\n  ],\n  \"video_url\": \"<string>\",\n  \"webhook\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.freemodel.app/v1/videos")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"seconds\": \"<string>\",\n  \"size\": \"<string>\",\n  \"aspect_ratio\": \"<string>\",\n  \"image_urls\": [\n    \"<string>\"\n  ],\n  \"video_url\": \"<string>\",\n  \"webhook\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

POST

videos

Video API workflow

curl --request POST \
  --url https://api.freemodel.app/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "prompt": "<string>",
  "seconds": "<string>",
  "size": "<string>",
  "aspect_ratio": "<string>",
  "image_urls": [
    "<string>"
  ],
  "video_url": "<string>",
  "webhook": "<string>"
}
'

import requests

url = "https://api.freemodel.app/v1/videos"

payload = {
    "model": "<string>",
    "prompt": "<string>",
    "seconds": "<string>",
    "size": "<string>",
    "aspect_ratio": "<string>",
    "image_urls": ["<string>"],
    "video_url": "<string>",
    "webhook": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    prompt: '<string>',
    seconds: '<string>',
    size: '<string>',
    aspect_ratio: '<string>',
    image_urls: ['<string>'],
    video_url: '<string>',
    webhook: '<string>'
  })
};

fetch('https://api.freemodel.app/v1/videos', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.freemodel.app/v1/videos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'prompt' => '<string>',
    'seconds' => '<string>',
    'size' => '<string>',
    'aspect_ratio' => '<string>',
    'image_urls' => [
        '<string>'
    ],
    'video_url' => '<string>',
    'webhook' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.freemodel.app/v1/videos"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"seconds\": \"<string>\",\n  \"size\": \"<string>\",\n  \"aspect_ratio\": \"<string>\",\n  \"image_urls\": [\n    \"<string>\"\n  ],\n  \"video_url\": \"<string>\",\n  \"webhook\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.freemodel.app/v1/videos")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"seconds\": \"<string>\",\n  \"size\": \"<string>\",\n  \"aspect_ratio\": \"<string>\",\n  \"image_urls\": [\n    \"<string>\"\n  ],\n  \"video_url\": \"<string>\",\n  \"webhook\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.freemodel.app/v1/videos")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"seconds\": \"<string>\",\n  \"size\": \"<string>\",\n  \"aspect_ratio\": \"<string>\",\n  \"image_urls\": [\n    \"<string>\"\n  ],\n  \"video_url\": \"<string>\",\n  \"webhook\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

All FreeModel video routes use the same asynchronous workflow. Choose a model from the Video Series sidebar, submit a request, save the returned id, and poll until the task completes. The model page defines the accepted duration, aspect ratio, resolution, image-reference, and source-video rules. Do not send values from one model family to another.

string

required

An available video model ID. Call GET /v1/models and select a model whose supported_endpoint_types includes openai-video.

string

required

Describe the subject, action, camera movement, lighting, and audio intent.

string

A model-specific duration. Send it only when the selected model page lists it. Do not send seconds with gemini-omni-extend.

string

Gemini Omni only. Use a supported 16:9 or 9:16 size: 1280x720, 720x1280, 1920x1080, or 1080x1920.

string

Seedance 2 and Veo 3.1 only. Do not send size with these routes.

string[]

Public http or https image URLs when the selected model accepts them. Follow its required count and per-image size limit.

string

The singular public http or https source-video URL required by gemini-omni-extend. Do not send an array.

string

Optional public callback URL. FreeModel sends the final task object when the task completes or fails.

Submit a task

curl https://api.freemodel.app/v1/videos \
  -H "Authorization: Bearer $FREEMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-ds-2.0-fast",
    "prompt": "A paper sculpture unfolds into a city skyline",
    "seconds": "5",
    "aspect_ratio": "16:9"
  }'

{
  "id": "task_01HXYZ",
  "object": "video",
  "status": "queued",
  "model": "video-ds-2.0-fast",
  "seconds": "5"
}

Poll and download

Include the same model query value while polling and downloading.

curl "https://api.freemodel.app/v1/videos/task_01HXYZ?model=video-ds-2.0-fast" \
  -H "Authorization: Bearer $FREEMODEL_API_KEY"

curl -L "https://api.freemodel.app/v1/videos/task_01HXYZ/content?model=video-ds-2.0-fast" \
  -H "Authorization: Bearer $FREEMODEL_API_KEY" \
  --output video.mp4

Poll every 10 to 20 seconds while status is queued or in_progress. Download only after status becomes completed.

Task status API

Query the normalized task record and final media URLs.

Webhooks

Receive the final task result without continuous polling.

Overview

Text Series

Image Series

Video Series

Endpoint Reference

Task Management

Video API workflow

Submit a task

Poll and download

Task status API

Webhooks

​Submit a task

​Poll and download

Task status API

Webhooks

Submit a task

Poll and download