Video Generation

Mesh API provides an async video generation endpoint that accepts text prompts, reference images, video clips, and audio tracks as inputs and returns a downloadable video URL.

Video generation is asynchronous. The POST endpoint creates a task and returns a task ID immediately. You then poll GET /v1/video/generations/{id} until the task reaches a terminal state, or receive the result passively via a webhook callback.

Base URL: https://api.meshapi.ai

Auth: Authorization: Bearer rsk_<your-key> on all requests.

Endpoints

Create a Video Generation Task

POST /v1/video/generations

Submits a video generation request. Returns immediately with {"id": "<task_id>"}.

Request body

Content items

The content array lets you combine different input modalities. Each item has a type field and a corresponding payload field.

Text prompt

1
{
2
  "type": "text",
3
  "text": "A slow-motion shot of waves crashing on a rocky coastline at sunset"
4
}

Image input (reference / first frame)

Pass a publicly accessible URL or a Base64-encoded image.

1
{ "type": "image_url", "image_url": { "url": "https://example.com/reference.jpg" } }

1
{ "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQ..." } }

Video input (reference video)

Seedance 2.0 series only. Pass a publicly accessible URL or a Base64-encoded video.

1
{ "type": "video_url", "video_url": { "url": "https://example.com/clip.mp4" } }

1
{ "type": "video_url", "video_url": { "url": "data:video/mp4;base64,AAAAIGZ0eXA..." } }

Audio input

Seedance 2.0 series only. Pass a publicly accessible URL or a Base64-encoded audio file.

1
{ "type": "audio_url", "audio_url": { "url": "https://example.com/soundtrack.mp3" } }

1
{ "type": "audio_url", "audio_url": { "url": "data:audio/mpeg;base64,SUQzBA..." } }

Input size limits

These limits apply to BytePlus Seedance models. Other providers may differ.

Video input

• Max file size: 50 MB per video

Audio input

• Supported formats: wav, mp3
• Duration per clip: 2–15 seconds; up to 3 reference audio clips allowed, with a total combined duration of no more than 15 seconds
• Max file size: 15 MB per audio file
• Max total request body size: 64 MB

For public URLs, the file must be reachable by the provider’s servers without authentication. For Base64 input, the data URI must include the MIME type prefix (e.g. data:video/mp4;base64,...).

Seedance input support matrix

Response

1
{ "id": "t-xxxxxxxxxxxxxxxx" }

Save the id to poll for status.

Example — text to video

$
curl -X POST https://api.meshapi.ai/v1/video/generations \
>
  -H "Authorization: Bearer rsk_your_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "model": "byteplus/dreamina-seedance-2-0",
>
    "content": [
>
      {
>
        "type": "text",
>
        "text": "A cinematic drone shot over a misty mountain valley at dawn"
>
      }
>
    ],
>
    "resolution": "1080p",
>
    "ratio": "16:9",
>
    "duration": 5,
>
    "generate_audio": false,
>
    "return_last_frame": true,
>
    "callback_url": "https://yourapp.example.com/webhooks/video"
>
  }'

Example — image to video

1
{
2
  "model": "byteplus/dreamina-seedance-2-0",
3
  "content": [
4
    {
5
      "type": "image_url",
6
      "image_url": { "url": "https://example.com/first-frame.jpg" }
7
    },
8
    {
9
      "type": "text",
10
      "text": "The subject slowly turns and walks toward the camera"
11
    }
12
  ],
13
  "duration": 5,
14
  "ratio": "9:16"
15
}

Example — video with audio input

1
{
2
  "model": "byteplus/dreamina-seedance-2-0",
3
  "content": [
4
    {
5
      "type": "text",
6
      "text": "A product reveal with dramatic lighting"
7
    },
8
    {
9
      "type": "audio_url",
10
      "audio_url": { "url": "https://example.com/background-music.mp3" }
11
    }
12
  ],
13
  "duration": 8,
14
  "generate_audio": false
15
}

Get Task Status

GET /v1/video/generations/{id}

Returns the current state of a task. For non-terminal tasks, Mesh API fetches the latest status from the upstream provider and syncs its database before responding.

Task statuses

Once a task reaches a terminal status (succeeded, failed, expired, cancelled), subsequent GET calls are served from the Mesh API database without hitting the upstream provider.

Response fields

Example — polling until complete

1
import time
2
import requests
3
4
TASK_ID = "t-xxxxxxxxxxxxxxxx"
5
headers = {"Authorization": "Bearer rsk_your_key"}
6
7
while True:
8
    res = requests.get(
9
        f"https://api.meshapi.ai/v1/video/generations/{TASK_ID}",
10
        headers=headers
11
    ).json()
12
13
    status = res["status"]
14
    print(f"Status: {status}")
15
16
    if status == "succeeded":
17
        print("Video URL:", res["content"]["video_url"])
18
        break
19
    elif status in ("failed", "expired", "cancelled"):
20
        print("Error:", res.get("error"))
21
        break
22
23
    time.sleep(5)

Succeeded response

1
{
2
  "id": "t-xxxxxxxxxxxxxxxx",
3
  "model": "byteplus/dreamina-seedance-2-0",
4
  "status": "succeeded",
5
  "content": {
6
    "video_url": "https://cdn.example.com/videos/generated.mp4",
7
    "last_frame_url": "https://cdn.example.com/videos/last-frame.jpg"
8
  },
9
  "usage": {
10
    "completion_tokens": 200,
11
    "total_tokens": 200
12
  },
13
  "resolution": "1080p",
14
  "ratio": "16:9",
15
  "duration": 5,
16
  "frames": 150,
17
  "framespersecond": 30,
18
  "created_at": 1718000000,
19
  "updated_at": 1718000180
20
}

Failed response

1
{
2
  "id": "t-xxxxxxxxxxxxxxxx",
3
  "model": "byteplus/dreamina-seedance-2-0",
4
  "status": "failed",
5
  "error": {
6
    "code": "content_policy_violation",
7
    "message": "The request could not be processed due to content policy."
8
  }
9
}

List Tasks

GET /v1/video/generations

Returns tasks stored in Mesh API’s database for your API key. This endpoint does not refresh task status from the upstream provider — use GET /v1/video/generations/{id} to force a live sync for an in-progress task.

Query parameters

Results are ordered by created_at descending (newest first).

Response

1
{
2
  "object": "list",
3
  "data": [
4
    {
5
      "id": "t-xxxxxxxxxxxxxxxx",
6
      "model": "byteplus/dreamina-seedance-2-0",
7
      "status": "succeeded",
8
      "created_at": 1718000000,
9
      "updated_at": 1718000180,
10
      "content": {
11
        "video_url": "https://cdn.example.com/videos/generated.mp4"
12
      }
13
    }
14
  ],
15
  "has_more": false,
16
  "total": 1,
17
  "limit": 50,
18
  "offset": 0
19
}

Webhooks

Instead of polling, you can pass a callback_url in the create request. Mesh API will POST the full task payload to your URL when the task reaches a terminal status (succeeded, failed, or expired).

How it works

1. You pass "callback_url": "https://yourapp.example.com/webhooks/video" in the create request.
2. Mesh API intercepts the completion notification from the upstream provider, updates its database, and then forwards the completed task payload to your callback_url.
3. Your endpoint receives a POST with a JSON body containing the final task state.

This means you never need to poll — just register a webhook endpoint and handle the event when it arrives.

Webhook payload

The payload is identical to the response from GET /v1/video/generations/{id}:

1
{
2
  "id": "t-xxxxxxxxxxxxxxxx",
3
  "model": "byteplus/dreamina-seedance-2-0",
4
  "status": "succeeded",
5
  "content": {
6
    "video_url": "https://cdn.example.com/videos/generated.mp4",
7
    "last_frame_url": "https://cdn.example.com/videos/last-frame.jpg"
8
  },
9
  "usage": {
10
    "completion_tokens": 200,
11
    "total_tokens": 200
12
  },
13
  "generate_audio": false,
14
  "resolution": "1080p",
15
  "ratio": "16:9",
16
  "duration": 5
17
}

Handling the webhook

Your endpoint should:

1. Return a 2xx response quickly. Mesh API fires the callback as fire-and-forget with a 10-second timeout — a slow response won’t block task completion on our side, but it will not be retried.
2. Identify the task from id in the payload.
3. Check status to decide what to do — download content.video_url on success, log or surface error on failure.

1
from flask import Flask, request, jsonify
2
3
app = Flask(__name__)
4
5
@app.route("/webhooks/video", methods=["POST"])
6
def video_webhook():
7
    task = request.json
8
    task_id = task["id"]
9
    status = task["status"]
10
11
    if status == "succeeded":
12
        video_url = task["content"]["video_url"]
13
        # save or process the video
14
        print(f"Task {task_id} succeeded: {video_url}")
15
    elif status == "failed":
16
        error = task.get("error", {})
17
        print(f"Task {task_id} failed: {error.get('code')} — {error.get('message')}")
18
    elif status == "expired":
19
        print(f"Task {task_id} expired before completing")
20
21
    return jsonify({"ok": True}), 200

Webhook vs polling — when to use each

You can use both simultaneously: pass a callback_url for production delivery and still poll GET /v1/video/generations/{id} as a fallback. Mesh API deduplicates usage logging so you are never billed twice.

Pricing

Video generation pricing is token-based and varies by the type of output:

The exact per-token rates for each model are listed on the Pricing page.

Error reference

When a task itself fails (HTTP 200, status: "failed"), the error.code and error.message fields describe the reason from the provider (e.g. content_policy_violation, invalid_input).