Refabric Docs

For AI agents: this page is also available as Markdown at https://docs.refabric.com/task-api-reference/video.generate.md, and the index of every page is https://docs.refabric.com/llms.txt.

Video

Make a video from an image

Turn a finished image into a short video, describing the movement you want while everything keeps the look it already has. Delivered as one video/mp4 file.

Endpoint: POST https://api.refabric.com/v1/tasks/video.generateTask: video.generateScope: tasks:runCategory: Video

Quick start

import os
import time
import requests

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

job = requests.post(
    "https://api.refabric.com/v1/tasks/video.generate",
    headers=headers,
    json={
        "image": "art:9f2c01",
        "prompt": "she turns towards the camera and smiles",
    },
).json()
print(job["job_id"])

while True:
    status = requests.get(job["status_url"], headers=headers).json()
    if status["lifecycle"] == "terminal":
        break
    time.sleep(5)

print(requests.get(job["result_url"], headers=headers).json())

cURL waits for the result with Prefer: wait; when the job outlives the wait, it answers 202 with the job's URLs.

Input schema

  • stringrequired

    What happens in the video ('she turns towards the camera and smiles'). Required and not blank; describe movement — the image already says what everything looks like.

    Example: she turns towards the camera and smiles

  • stringrequired

    The finished image to animate; it is the video's first frame. As one string: a URL, a file from an earlier result (art:… or its url) or an upload (file:…). If it is one of your files placed in a project or on a design in the Refabric app, the result is filed there too.

    pattern: ^(https://|art:|file:).+$

    Example: art:9f2c01

  • stringoptionalDefault: 4

    How long the video is, in seconds. A video with references is always 8 seconds long. With nothing sent the video is 4 seconds long; send 8 for a longer clip.

    Values

    • 4 — Four seconds.
    • 8 — Eight seconds. When the motion needs more time, such as a full turn or a longer walk.

    Example: 8

  • stringoptionalDefault: standard

    How carefully the video is rendered. With nothing sent you get standard, the faster of the two renderings, which suits previews and most videos; ask for premium when the video is final work.

    Values

    • standard — Made quickly; right for previews and most uses.
    • premium — Rendered with more care. Takes longer. When the video is final work and detail matters more than speed.

    Example: standard

  • array<object>optional

    Up to 3 other angles of the same garment, each {image}. Sending any makes the video from the image and these angles together, and it is then always 8 seconds long.

    at most 3 items

Output schema

  • array<object>optional

    One video/mp4 file.

Required-fields example

{
  "image": "art:9f2c01",
  "prompt": "she turns towards the camera and smiles"
}

Full example

{
  "image": "art:9f2c01",
  "prompt": "she turns towards the camera and smiles",
  "duration": "8",
  "quality": "standard"
}

Response example

{
  "job_id": "d2b3c4d5000040008000000000000010",
  "lifecycle": "queued",
  "status_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d5000040008000000000000010",
  "result_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d5000040008000000000000010/result",
  "cancel_url": "http://v3-api.refabric.com/v1/jobs/d2b3c4d5000040008000000000000010/cancel"
}

Result example

{
  "job_id": "d2b3c4d5000040008000000000000010",
  "files": [
    {
      "file": "art:9f2c0a",
      "url": "https://files.example.com/video.generate/1.mp4",
      "media_type": "video/mp4",
      "task": "video.generate",
      "job_id": "d2b3c4d5000040008000000000000010",
      "created_at": "2026-10-01T09:52:47Z"
    }
  ],
  "has_more": false
}

duration and quality take the values their fields list in the input schema. With references[{image}] (up to the schema's maxItems) the video takes the longer duration.

Send a finished image and describe the movement you want; you get a short video in which everything keeps the look it already has. Pick its length with `duration` and how it is rendered with `quality`, and send other angles of the same garment in `references` when the video should show more of it.

Built for

  • A product page video from a shoot image
  • Short clips for social posts
  • A garment shown turning or walking

What you get

  • One video/mp4 file of the movement you described.

Prompting

Describe movement, not looks: what the person or the garment does ('she turns towards the camera and smiles'). The image already says what everything looks like.

Specs

Input formatsImages, each one string: a URL, an upload (file:…) or a file from an earlier result (art:…). Upload types and sizes: GET /v1/meta limits.upload.
Input countimage: one; references: up to 3, each with its image
Output formatFiles: each one line with its url and its media_type, in the job's result.
Outputs per jobOne video file per job.

Errors

Related

Good to know

  • references holds at most 3 items.

Pricing: Estimate a request before you run it, or see the price of each option.

For agents and code generation

Schema changes follow Versioning.