> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neural4d.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a video generation task and retrieve its result.

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.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.neural4d.com/openapi/v1/files' \
    --header 'Authorization: Bearer ${YOUR_API_KEY}' \
    --form 'file=@first-frame.png'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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());
  ```

  ```go Go theme={null}
  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))
  }
  ```
</CodeGroup>

```json 201 Created theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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());
  ```

  ```go Go theme={null}
  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))
  }
  ```
</CodeGroup>

```json 202 Accepted theme={null}
{
  "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.

```bash cURL theme={null}
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`.

```json 200 OK theme={null}
{
  "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](/en/common-headers) for authentication and request tracing.