Quickstart

API v1 uses the https://api.neural4d.com/openapi/v1 base path. Send your API key with every request.

Upload a reference file

Upload one local image or video with POST /files. Store the returned file id for generation requests.

curl --request POST \
  --url 'https://api.neural4d.com/openapi/v1/files' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --form 'file=@first-frame.png'

import os
import requests

with open("first-frame.png", "rb") as file:
    response = requests.post(
        "https://api.neural4d.com/openapi/v1/files",
        headers={"Authorization": f"Bearer {os.environ['YOUR_API_KEY']}"},
        files={"file": ("first-frame.png", file, "image/png")},
    )

print(response.json())

import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("first-frame.png"), "first-frame.png");

const response = await fetch("https://api.neural4d.com/openapi/v1/files", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.YOUR_API_KEY}` },
  body: form,
});

console.log(await response.json());

package main

import (
    "bytes"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
    "path/filepath"
)

func main() {
    file, _ := os.Open("first-frame.png")
    defer file.Close()

    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    part, _ := writer.CreateFormFile("file", filepath.Base(file.Name()))
    _, _ = io.Copy(part, file)
    _ = writer.Close()

    request, _ := http.NewRequest("POST", "https://api.neural4d.com/openapi/v1/files", body)
    request.Header.Set("Authorization", "Bearer "+os.Getenv("YOUR_API_KEY"))
    request.Header.Set("Content-Type", writer.FormDataContentType())

    response, _ := http.DefaultClient.Do(request)
    defer response.Body.Close()
    result, _ := io.ReadAll(response.Body)
    fmt.Println(string(result))
}

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "first-frame.png",
  "bytes": 245760,
  "mime_type": "image/png",
  "created_at": 1784044800
}

Create a video

Submit a JSON request to POST /videos/generations. Put first-frame and last-frame images in frame_images; use input_references for other image, video, or audio references. Set output_with_audio for Seedance 2.0, Seedance 2.0 Fast, or Veo 3.1 to control native audio generation. Omit it for xai/grok-imagine; if you omit it for a supported model, that model’s configured default applies. This example animates the uploaded first-frame image by its file ID. The API returns 202 Accepted with a task ID.

curl --request POST \
  --url 'https://api.neural4d.com/openapi/v1/videos/generations' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "bytedance/seedance-2.0-fast",
    "prompt": "A cinematic tracking shot through a neon-lit street at night",
    "frame_images": [
      {
        "type": "image",
        "frame_type": "first_frame",
        "file_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "output_with_audio": true,
    "n": 1
  }'

import os
import requests

response = requests.post(
    "https://api.neural4d.com/openapi/v1/videos/generations",
    headers={"Authorization": f"Bearer {os.environ['YOUR_API_KEY']}"},
    json={
        "model": "bytedance/seedance-2.0-fast",
        "prompt": "A cinematic tracking shot through a neon-lit street at night",
        "frame_images": [
            {
                "type": "image",
                "frame_type": "first_frame",
                "file_id": "550e8400-e29b-41d4-a716-446655440000",
            },
        ],
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "output_with_audio": True,
        "n": 1,
    },
)
print(response.json())

const response = await fetch("https://api.neural4d.com/openapi/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.YOUR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "bytedance/seedance-2.0-fast",
    prompt: "A cinematic tracking shot through a neon-lit street at night",
    frame_images: [
      {
        type: "image",
        frame_type: "first_frame",
        file_id: "550e8400-e29b-41d4-a716-446655440000",
      },
    ],
    duration: 5,
    resolution: "720p",
    aspect_ratio: "16:9",
    output_with_audio: true,
    n: 1,
  }),
});

console.log(await response.json());

package main

import (
    "bytes"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    body := []byte(`{"model":"bytedance/seedance-2.0-fast","prompt":"A cinematic tracking shot through a neon-lit street at night","frame_images":[{"type":"image","frame_type":"first_frame","file_id":"550e8400-e29b-41d4-a716-446655440000"}],"duration":5,"resolution":"720p","aspect_ratio":"16:9","output_with_audio":true,"n":1}`)
    request, _ := http.NewRequest("POST", "https://api.neural4d.com/openapi/v1/videos/generations", bytes.NewReader(body))
    request.Header.Set("Authorization", "Bearer "+os.Getenv("YOUR_API_KEY"))
    request.Header.Set("Content-Type", "application/json")

    response, _ := http.DefaultClient.Do(request)
    defer response.Body.Close()
    result, _ := io.ReadAll(response.Body)
    fmt.Println(string(result))
}

202 Accepted

{
  "id": "normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d",
  "status": "queued",
  "created_at": 1784044800,
  "mode": "first_frame_image_to_video",
  "model": "bytedance/seedance-2.0-fast",
  "data": [
    {
      "uuid": "7d1fa4bb-41e6-4a5d-88d8-1851f5342e87",
      "status": "queued",
      "created_at": 1784044800
    }
  ]
}

Retrieve the task

Pass exactly one of the batch task id or child video uuid to GET /tasks/task-info. Poll until status is succeeded or failed. Each item in output.videos includes its child UUID, aspect ratio, native audio flag, generation mode, status, and timestamps.

cURL

curl --request GET \
  --url 'https://api.neural4d.com/openapi/v1/tasks/task-info?id=normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'

To query directly by a generated video UUID, use uuid instead of id: GET /openapi/v1/tasks/task-info?uuid=7d1fa4bb-41e6-4a5d-88d8-1851f5342e87.

200 OK

{
  "id": "normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d",
  "status": "succeeded",
  "mode": "first_frame_image_to_video",
  "model": "bytedance/seedance-2.0-fast",
  "created_at": 1784044800,
  "updated_at": 1784044842,
  "output": {
    "videos": [
      {
        "uuid": "7d1fa4bb-41e6-4a5d-88d8-1851f5342e87",
        "url": "https://cdn.neural4d.com/results/video.mp4",
        "format": "mp4",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "has_audio": true,
        "mode": "first_frame_image_to_video",
        "status": "succeeded",
        "created_at": 1784044800,
        "updated_at": 1784044842
      }
    ]
  }
}

See Common headers for authentication and request tracing.

Get started

API reference

Upload a reference file

Create a video

Retrieve the task

​Upload a reference file

​Create a video

​Retrieve the task

Upload a reference file

Create a video

Retrieve the task