API Reference

Endpoint:

POST /v2/ltx-2.3/fast

Schema

Input

Send a JSON object with the generation parameters.

Field	Type	Required	Description
`prompt`	string	required	Text description of the video to generate.
`duration`	number	required	Clip length in seconds: `5` or `8`.
`resolution`	string	required	`1920x1088`, `1088x1920`, `1280x768`, or `768x1280`.
`seed`	integer	optional	Seed used to reproduce a generation.
`image_url`	string	optional	Condition the first frame on a public HTTPS image URL.
`image_strength`	number	optional	Image-conditioning strength from `0` to `1`.
`image_inputs`	array<object>	optional	Frame-specific image conditioning. Each object provides exactly one of `url` or `data`, plus `frame_idx` and `strength`. Use `data` for an inline `data:image/...` URI.

Output

The API returns binary media on success and structured JSON when a request fails.

Status	Content type	Body
`200`	`video/mp4`	Binary MP4 data.
`4xx / 5xx`	`application/json`	Error code and human-readable message.

Setup API key

Export your key in the shell before making a request.

export TENSORSCALE_API_KEY="your-api-key"

Examples

Text-to-video generation

curl "https://api.tensorscale.io/v2/ltx-2.3/fast" \
  -H "Authorization: Bearer ${TENSORSCALE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A fluffy kitten looks at the camera and tilts its head.",
    "duration": 5,
    "resolution": "1280x768",
    "seed": 42
  }' \
  --output "kitten.mp4"

import os
import requests

resp = requests.post(
    "https://api.tensorscale.io/v2/ltx-2.3/fast",
    json={
        "prompt": "A fluffy kitten looks at the camera and tilts its head.",
        "duration": 5,
        "resolution": "1280x768",
        "seed": 42,
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
    },
)
resp.raise_for_status()
open("kitten.mp4", "wb").write(resp.content)

Image-to-video with a public URL

Pass a public HTTPS image URL to condition the first frame of the generated video.

curl "https://api.tensorscale.io/v2/ltx-2.3/fast" \
  -H "Authorization: Bearer ${TENSORSCALE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic aerial push toward the lighthouse as ocean waves roll against the cliffs.",
    "duration": 5,
    "resolution": "1280x768",
    "seed": 42,
    "image_url": "https://example.com/coastal-lighthouse.jpg",
    "image_strength": 1.0
  }' \
  --output "lighthouse.mp4"

import os
import requests

resp = requests.post(
    "https://api.tensorscale.io/v2/ltx-2.3/fast",
    json={
        "prompt": "A cinematic aerial push toward the lighthouse as ocean waves roll against the cliffs.",
        "duration": 5,
        "resolution": "1280x768",
        "seed": 42,
        "image_url": "https://example.com/coastal-lighthouse.jpg",
        "image_strength": 1.0,
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
    },
    timeout=600,
)
resp.raise_for_status()
open("lighthouse.mp4", "wb").write(resp.content)

Image-to-video with a local file

Read a local image and send it as an inline Base64 data URI. The API does not accept a client-local filesystem path directly.

import base64
import os
from pathlib import Path

import requests

def data_uri(path: Path) -> str:
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return f"data:image/png;base64,{encoded}"

resp = requests.post(
    "https://api.tensorscale.io/v2/ltx-2.3/fast",
    json={
        "prompt": "A cinematic aerial push toward the lighthouse as ocean waves roll against the cliffs.",
        "duration": 5,
        "resolution": "1280x768",
        "seed": 42,
        "image_inputs": [
            {
                "data": data_uri(Path("coastal-lighthouse.png")),
                "frame_idx": 0,
                "strength": 1.0,
            }
        ],
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
    },
    timeout=600,
)
resp.raise_for_status()
Path("lighthouse-local.mp4").write_bytes(resp.content)

Endpoint:

POST /v2/MiniMax-H3/fl2va

Schema

Input

The endpoint performs text-to-audio-video generation when both frame fields are omitted, or frame-conditioned generation when either field is supplied.

Field	Type	Required	Description
`prompt`	string	required	Text description of the synchronized video and audio to generate.
`first_image`	string	optional	First-frame image as a base64 image data URI.
`last_image`	string	optional	Last-frame image as a base64 image data URI.
`aspect_ratio`	string	optional	Width-to-height ratio in positive-integer `W:H` form. Defaults to `"16:9"`. Any ratio from `1:4` through `4:1` is accepted, including `"4:1"`, `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, and `"1:4"`. The service derives the output canvas from this field.
`duration_seconds`	number	required	Positive target duration in seconds. The service aligns it to MiniMax H3's native 24 fps, `17n+5` frame boundary.
`num_inference_steps`	integer	optional	Number of scheduler points. Must be greater than `1`; the native profile uses `50`.
`flow_shift`	number	optional	Video scheduler flow shift. The current service profile requires `12.0`.
`audio_flow_shift`	number	optional	Audio scheduler flow shift. The current service profile requires `3.0`.
`seed`	integer	optional	Seed used to reproduce a generation. Defaults to `1101`.

Common ratios produce these canvases: 4:1 → 2016×512, 21:9 → 1536×672, 16:9 → 1344×768, 4:3 → 1024×768, 1:1 → 768×768, 3:4 → 768×1024, 9:16 → 768×1344, and 1:4 → 512×2016.

The complete JSON body may be up to 10 MiB. The first supplied frame is stretched onto the requested canvas; when both images are supplied, the last image is cover-cropped onto that canvas.

Output

The API returns the generated audio-video file directly on success and structured JSON when a request fails.

Status	Content type	Body
`200`	`video/mp4`	Binary MP4 data containing H.264 video and AAC audio.
`4xx / 5xx`	`application/json`	Error code and human-readable message.

Setup API key

Export your key in the shell before making a request. The key must be authorized for model MiniMax-H3.

export TENSORSCALE_API_KEY="your-api-key"

Example

Text-to-audio-video generation

curl "https://api.tensorscale.io/v2/MiniMax-H3/fl2va" \
  -H "Authorization: Bearer ${TENSORSCALE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: video/mp4" \
  -d '{
    "prompt": "At night, while their owner sleeps in a bedroom, three cats march in loudly playing tiny brass instruments, then abruptly file out.",
    "aspect_ratio": "16:9",
    "duration_seconds": 5.0,
    "num_inference_steps": 50,
    "flow_shift": 12.0,
    "audio_flow_shift": 3.0,
    "seed": 1101
  }' \
  --output "brass-band-cats.mp4"

import os
from pathlib import Path

import requests

resp = requests.post(
    "https://api.tensorscale.io/v2/MiniMax-H3/fl2va",
    json={
        "prompt": (
            "At night, while their owner sleeps in a bedroom, three cats march "
            "in loudly playing tiny brass instruments, then abruptly file out."
        ),
        "aspect_ratio": "16:9",
        "duration_seconds": 5.0,
        "num_inference_steps": 50,
        "flow_shift": 12.0,
        "audio_flow_shift": 3.0,
        "seed": 1101,
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
        "Accept": "video/mp4",
    },
    timeout=600,
)
resp.raise_for_status()
Path("brass-band-cats.mp4").write_bytes(resp.content)

Frame-conditioned example

First- and last-frame-conditioned generation

import base64
import os
from pathlib import Path

import requests

def data_uri(path: Path) -> str:
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return f"data:image/jpeg;base64,{encoded}"

resp = requests.post(
    "https://api.tensorscale.io/v2/MiniMax-H3/fl2va",
    json={
        "prompt": "A cinematic aerial push toward a lighthouse as waves roll against the cliffs.",
        "first_image": data_uri(Path("lighthouse-start.jpg")),
        "last_image": data_uri(Path("lighthouse-end.jpg")),
        "aspect_ratio": "16:9",
        "duration_seconds": 5.0,
        "num_inference_steps": 50,
        "flow_shift": 12.0,
        "audio_flow_shift": 3.0,
        "seed": 1101,
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
        "Accept": "video/mp4",
    },
    timeout=1800,
)
resp.raise_for_status()
Path("lighthouse-transition.mp4").write_bytes(resp.content)

Endpoint:

POST /v2/sensenova-u1.5/t2i

Schema

Input

Send a JSON object for text-to-image generation. The current service profile is fixed to the golden 2048×2048 / 50-step request.

Field	Type	Required	Description
`prompt`	string	required	Text description of the image to generate.
`size`	string	optional	Must be `2048x2048` in the current service profile. Defaults to `2048x2048`.
`seed`	integer	optional	Seed used to reproduce a generation. Defaults to `42`.
`cfg_scale`	number	optional	Must be `4.0` in the current service profile.
`timestep_shift`	number	optional	Must be `3.0` in the current service profile.

Output

The API returns the generated image directly on success and structured JSON when a request fails.

Status	Content type	Body
`200`	`image/png`	Binary PNG data.
`4xx / 5xx`	`application/json`	Error code and human-readable message.

Setup API key

Export your key in the shell before making a request. The key must be authorized for model SenseNova-U1.5.

export TENSORSCALE_API_KEY="your-api-key"

Example

curl "https://api.tensorscale.io/v2/sensenova-u1.5/t2i" \
  -H "Authorization: Bearer ${TENSORSCALE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: image/png" \
  -d '{
    "prompt": "A cinematic mountain lake at sunrise, realistic photography.",
    "seed": 42,
    "size": "2048x2048"
  }' \
  --output "lake.png"

import os
import requests

resp = requests.post(
    "https://api.tensorscale.io/v2/sensenova-u1.5/t2i",
    json={
        "prompt": "A cinematic mountain lake at sunrise, realistic photography.",
        "seed": 42,
        "size": "2048x2048",
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
        "Accept": "image/png",
    },
    timeout=1800,
)
resp.raise_for_status()
open("lake.png", "wb").write(resp.content)

Endpoint:

POST /v2/hunyuan-image-3-instruct/fast

Schema

Input

Send a JSON object for text-to-image generation or image editing.

Field	Type	Required	Description
`prompt`	string	required	Text description of the image to generate or the edit to apply.
`images`	array<string \| object>	optional	Up to two image references. Each entry may be a URI string or an object containing `uri`. Inline `data:image/...` URIs and public HTTPS URLs are supported. Use an empty array for text-to-image.
`bot_task`	string	optional	`image`, `recaption`, `think`, or `think_recaption`. Defaults to `image`.
`seed`	integer	optional	Seed used to reproduce a generation. Defaults to `43`.

Output

The API returns the generated image directly on success and structured JSON when a request fails.

Status	Content type	Body
`200`	`image/jpeg`	Binary JPEG data.
`4xx / 5xx`	`application/json`	Error code and human-readable message.

Setup API key

Export your key in the shell before making a request.

export TENSORSCALE_API_KEY="your-api-key"

Example

Image generation

curl "https://api.tensorscale.io/v2/hunyuan-image-3-instruct/fast" \
  -H "Authorization: Bearer ${TENSORSCALE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: image/jpeg" \
  -d '{
    "prompt": "A red apple on a white table",
    "images": [],
    "bot_task": "image",
    "seed": 42
  }' \
  --output "apple.jpg"

import os
import requests

resp = requests.post(
    "https://api.tensorscale.io/v2/hunyuan-image-3-instruct/fast",
    json={
        "prompt": "A red apple on a white table",
        "images": [],
        "bot_task": "image",
        "seed": 42,
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
        "Accept": "image/jpeg",
    },
    timeout=600,
)
resp.raise_for_status()
open("apple.jpg", "wb").write(resp.content)

Image editing with two references

Pass public HTTPS URLs with uri. The first image is the edit target and the second is a visual reference.

curl "https://api.tensorscale.io/v2/hunyuan-image-3-instruct/fast" \
  -H "Authorization: Bearer ${TENSORSCALE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: image/jpeg" \
  -d '{
    "prompt": "Replace the chair in the room with the chair shown in the reference image. Preserve the room layout, lighting, and perspective.",
    "images": [
      {"uri": "https://example.com/living-room.jpg"},
      {"uri": "https://example.com/chair-reference.jpg"}
    ],
    "bot_task": "image",
    "seed": 42
  }' \
  --output "room-edit.jpg"

import os
import requests

resp = requests.post(
    "https://api.tensorscale.io/v2/hunyuan-image-3-instruct/fast",
    json={
        "prompt": "Replace the chair in the room with the chair shown in the reference image. Preserve the room layout, lighting, and perspective.",
        "images": [
            {"uri": "https://example.com/living-room.jpg"},
            {"uri": "https://example.com/chair-reference.jpg"},
        ],
        "bot_task": "image",
        "seed": 42,
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
        "Accept": "image/jpeg",
    },
    timeout=600,
)
resp.raise_for_status()
open("room-edit.jpg", "wb").write(resp.content)

Image editing with local files

Read local images and send them as inline Base64 data URIs. The API does not accept local filesystem paths directly.

import base64
import os
from pathlib import Path

import requests

def data_uri(path: Path) -> str:
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return f"data:image/png;base64,{encoded}"

resp = requests.post(
    "https://api.tensorscale.io/v2/hunyuan-image-3-instruct/fast",
    json={
        "prompt": "Replace the chair in the room with the chair shown in the reference image. Preserve the room layout, lighting, and perspective.",
        "images": [
            data_uri(Path("living-room.png")),
            data_uri(Path("chair-reference.png")),
        ],
        "bot_task": "image",
        "seed": 42,
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
        "Accept": "image/jpeg",
    },
    timeout=600,
)
resp.raise_for_status()
Path("room-edit-local.jpg").write_bytes(resp.content)

Endpoint

Schema

Input

Send a JSON object for text-to-video generation. The endpoint selects text-to-video mode automatically.

Field	Type	Required	Description
`prompt`	string	required	Text description of the video to generate.
`seconds`	number	required	Requested clip length in seconds. The service converts this duration to a valid Cosmos frame count.
`fps`	integer	required	Output frame rate. Use `24` for the native generation profile.
`resolution`	string	optional	Output height profile: `256`, `480`, `704`, `720`, or `768`. Defaults to `720`.
`aspect_ratio`	string	optional	Width-to-height ratio, encoded as a comma-separated string. Accepted values: `"1,1"` (square), `"4,3"` (landscape), `"3,4"` (portrait), `"16,9"` (widescreen), and `"9,16"` (vertical). Defaults to `"16,9"`.
`num_steps`	integer	optional	Number of diffusion steps. The native default is `35`.
`guidance`	number	optional	Prompt guidance strength. The native default is `6.0`.
`seed`	integer	optional	Seed used to reproduce a generation.

Output

The API returns the generated video directly on success and structured JSON when a request fails.

Status	Content type	Body
`200`	`video/mp4`	Binary MP4 data.
`4xx / 5xx`	`application/json`	Error code and human-readable message.

Setup API key

Export your key in the shell before making a request.

export TENSORSCALE_API_KEY="your-api-key"

Example

Text-to-video generation

curl "https://api.tensorscale.io/v2/cosmos3-nano/t2v" \
  -H "Authorization: Bearer ${TENSORSCALE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: video/mp4" \
  -d '{
    "prompt": "A cinematic foundry scene with glowing molten metal pouring into a mold.",
    "seconds": 8,
    "fps": 24,
    "resolution": "720",
    "aspect_ratio": "16,9",
    "num_steps": 35,
    "guidance": 6.0,
    "seed": 0
  }' \
  --output "foundry.mp4"

import os
from pathlib import Path

import requests

resp = requests.post(
    "https://api.tensorscale.io/v2/cosmos3-nano/t2v",
    json={
        "prompt": "A cinematic foundry scene with glowing molten metal pouring into a mold.",
        "seconds": 8,
        "fps": 24,
        "resolution": "720",
        "aspect_ratio": "16,9",
        "num_steps": 35,
        "guidance": 6.0,
        "seed": 0,
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
        "Accept": "video/mp4",
    },
    timeout=1810,
)
resp.raise_for_status()
Path("foundry.mp4").write_bytes(resp.content)

Schema

Input

Send a source video and prompt describing its realistic target appearance. The endpoint selects video-to-video mode automatically while preserving the source motion and composition.

Field	Type	Required	Description
`prompt`	string	required	Description of the target video appearance.
`video`	string	required	Source video as a public HTTPS URL or inline Base64 data URI such as `data:video/mp4;base64,...`.
`seconds`	number	required	Requested clip length in seconds. The service converts this duration to a valid Cosmos frame count.
`fps`	integer	required	Output frame rate. Use `24` to match the native generation profile.
`resolution`	string	optional	Output height profile: `256`, `480`, `704`, `720`, or `768`. Defaults to `720`.
`aspect_ratio`	string	optional	Width-to-height ratio. Use `"1,1"`, `"4,3"`, `"3,4"`, `"16,9"`, or `"9,16"`. Defaults to `"16,9"`.
`num_steps`	integer	optional	Number of diffusion steps. Use `50` for a high-quality transformation.
`guidance`	number	optional	Prompt guidance strength.
`seed`	integer	optional	Seed used to reproduce a generation.

Output

The API returns the transformed video directly on success and structured JSON when a request fails.

Status	Content type	Body
`200`	`video/mp4`	Binary MP4 data.
`4xx / 5xx`	`application/json`	Error code and human-readable message.

Setup API key

Export your key in the shell before making a request.

export TENSORSCALE_API_KEY="your-api-key"

Example

Simulation-to-real video transformation

curl "https://api.tensorscale.io/v2/cosmos3-nano/v2v" \
  -H "Authorization: Bearer ${TENSORSCALE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: video/mp4" \
  -d '{
    "prompt": "Transform this robot simulation into photorealistic live-action footage while preserving its camera, geometry, object positions, timing, and motion.",
    "video": "https://example.com/robot-simulation.mp4",
    "seconds": 5,
    "fps": 24,
    "resolution": "720",
    "aspect_ratio": "16,9",
    "num_steps": 50,
    "guidance": 4.5,
    "seed": 2026
  }' \
  --output "robot-realistic.mp4"

import base64
import os
from pathlib import Path

import requests

source = Path("robot_cg.mp4")
video = "data:video/mp4;base64," + base64.b64encode(source.read_bytes()).decode("ascii")

resp = requests.post(
    "https://api.tensorscale.io/v2/cosmos3-nano/v2v",
    json={
        "prompt": (
            "Transform the simulation into photorealistic live-action footage of a "
            "luxury kitchen. Preserve the camera, robot geometry, object positions, "
            "timing, and motion exactly. Use physically accurate materials, shadows, "
            "reflections, and natural cinematic lighting."
        ),
        "video": video,
        "seconds": 5,
        "fps": 24,
        "resolution": "720",
        "aspect_ratio": "16,9",
        "num_steps": 50,
        "guidance": 4.5,
        "seed": 2026,
    },
    headers={
        "Authorization": f"Bearer {os.environ['TENSORSCALE_API_KEY']}",
        "Accept": "video/mp4",
    },
    timeout=1810,
)
resp.raise_for_status()
Path("robot-realistic.mp4").write_bytes(resp.content)