FLUX 3 Video Draft Text to Video

This documentation is valid for the following list of our models:

• blackforestlabs/flux-3-video-draft-t2v

Try in Playground

Model Overview

Fast hd-only draft mode of FLUX 3 Video text-to-video, for previewing a prompt before paying for a full-quality render.

Setup your API Key

If you don't have an API key yet, use our Quickstart guide.

How to Make a Call

Step-by-Step Instructions

Generating a video involves sequentially calling two endpoints:

• Create and submit a video generation task. The response contains a generation ID.

• Poll the retrieval endpoint with that generation ID until the status is completed.

API Schemas

Create a video generation task and send it to the server

post

Body

modelstring · enumRequiredPossible values:

promptstring · min: 1Required

The text prompt describing the video to generate.

aspect_ratiostring · enumOptional

The aspect ratio of the generated video. auto lets the model pick, and image-to-video follows the first keyframe.

Default: autoPossible values:

durationinteger · min: 5 · max: 20Optional

The video length in whole seconds, from 5 to 20.

Default: 5

generate_audiobooleanOptional

Whether to generate a synchronized audio track. Set to false for a silent clip.

Default: true

safety_toleranceinteger · max: 4Optional

The moderation strictness, from 0 (strictest) to 4 (most permissive).

Default: 2

resolutionstring · enumOptional

The output resolution of the generated video. Draft generations are hd-only; use the non-draft model for fhd.

Default: hdPossible values:

Responses

200

Successful response.

application/json

idstringRequired

The ID of the generated video.

Example: 60ac7c34-3224-4b14-8e7d-0aa0db708325

statusstring · enumRequired

The current status of the generation task.

Example: completedPossible values:

videoany ofOptional

or

or

any · nullableOptional

post/v2/video/generations

curl --request POST \
  --url 'https://api.aimlapi.com/v2/video/generations' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"model": "blackforestlabs/flux-3-video-draft-t2v", "prompt": "Describe what you want the model to generate.", "duration": 5}'

200

Successful response.

{
  "id": "60ac7c34-3224-4b14-8e7d-0aa0db708325",
  "status": "completed",
  "video": {
    "url": "https://cdn.aimlapi.com/generations/hedgehog/1759866285599-0cdfb138-c03a-49d4-a601-4f6413e27b15.mp4"
  },
  "error": {
    "name": "text",
    "message": "text"
  },
  "meta": {
    "usage": {
      "credits_used": 120000,
      "usd_spent": 0.06
    }
  }
}

Retrieve the generated video from the server

Poll this endpoint with the generation_id returned by the submit request. When the status is completed, the response includes the generated video URL.

get

Authorizations

AuthorizationstringRequired

Bearer key

Query parameters

generation_idstringRequiredExample: <REPLACE_WITH_YOUR_GENERATION_ID>

Responses

200Success

application/json

idstringRequired

The ID of the generated video.

Example: 60ac7c34-3224-4b14-8e7d-0aa0db708325

statusstring · enumRequired

The current status of the generation task.

Example: completedPossible values:

get/v2/video/generations

curl -L \
  --request GET \
  --url 'https://api.aimlapi.com/v2/video/generations?generation_id=<REPLACE_WITH_YOUR_GENERATION_ID>' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>'

200Success

{
  "id": "60ac7c34-3224-4b14-8e7d-0aa0db708325",
  "status": "completed",
  "video": {
    "url": "https://cdn.aimlapi.com/generations/hedgehog/1759866285599-0cdfb138-c03a-49d4-a601-4f6413e27b15.mp4"
  },
  "error": {
    "name": "text",
    "message": "text"
  },
  "meta": {
    "usage": {
      "credits_used": 120000
    }
  }
}

Code Example

The examples submit a generation task and poll every 15 seconds until the final result is available.

Python

import requests
import time

api_key = "<YOUR_AIMLAPI_KEY>"
url = "https://api.aimlapi.com/v2/video/generations"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

generation = requests.post(url, headers=headers, json={'model': 'blackforestlabs/flux-3-video-draft-t2v', 'prompt': 'Describe what you want the model to generate.', 'duration': 5, 'image_url': 'https://example.com/input.jpg'})
generation.raise_for_status()
generation_id = generation.json()["id"]

while True:
    result = requests.get(
        url,
        headers=headers,
        params={"generation_id": generation_id},
    )
    result.raise_for_status()
    data = result.json()
    if data.get("status") not in ("queued", "generating"):
        print(data)
        break
    time.sleep(15)

JavaScript

const apiKey = "<YOUR_AIMLAPI_KEY>";
const url = "https://api.aimlapi.com/v2/video/generations";
const headers = {
  "Authorization": `Bearer ${apiKey}`,
  "Content-Type": "application/json",
};

const generation = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "blackforestlabs/flux-3-video-draft-t2v",
  "prompt": "Describe what you want the model to generate.",
  "duration": 5,
  "image_url": "https://example.com/input.jpg"
}),
});
const { id: generationId } = await generation.json();

while (true) {
  const response = await fetch(
    `${url}?generation_id=${encodeURIComponent(generationId)}`,
    { headers },
  );
  const data = await response.json();
  if (!["queued", "generating"].includes(data.status)) {
    console.log(data);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 15000));
}

Response

{
  "id": "60ac7c34-3224-4b14-8e7d-0aa0db708325",
  "status": "completed",
  "video": {
    "url": "https://cdn.aimlapi.com/generations/hedgehog/1759866285599-0cdfb138-c03a-49d4-a601-4f6413e27b15.mp4"
  },
  "error": {
    "name": "<name>",
    "message": "<message>"
  },
  "meta": {
    "usage": {
      "credits_used": 120000,
      "usd_spent": 0.06
    }
  },
  "model": "blackforestlabs/flux-3-video-draft-t2v"
}