Video Generation - Mesh API

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

Method	Path	Description
`POST`	`/v1/video/generations`	Create a video generation task
`GET`	`/v1/video/generations/{id}`	Get task status and result
`GET`	`/v1/video/generations`	List your tasks

Create a Video Generation Task

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

Request body

Field	Type	Required	Description
`model`	string	Yes	Model ID, e.g. `byteplus/dreamina-seedance-2-0`.
`content`	array	Yes	Array of content items (see Content items).
`callback_url`	string	No	Your URL to receive a POST when the task completes.
`resolution`	string	No	Output resolution, e.g. `720p`, `1080p`.
`ratio`	string	No	Aspect ratio, e.g. `16:9`, `9:16`, `1:1`.
`duration`	integer	No	Target video duration in seconds.
`frames`	integer	No	Target frame count (use `duration` or `frames`, not both).
`generate_audio`	boolean	No	Generate an audio track alongside the video. Pricing differs when enabled.
`return_last_frame`	boolean	No	Include a still image of the final frame in the result.
`seed`	integer	No	Reproducible generation seed.
`camera_fixed`	boolean	No	Lock the camera position (no camera movement).
`watermark`	boolean	No	Add a provider watermark to the output.
`draft`	boolean	No	Generate a fast draft preview.
`service_tier`	string	No	Provider service tier selection.
`execution_expires_after`	integer	No	Seconds until the task expires if not completed (default 172800 = 48 h).
`priority`	integer 0–9	No	Task priority hint. Higher = more urgent.
`safety_identifier`	string	No	Pass a safety policy identifier for content moderation.

Content items

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

Text prompt

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

Image input (reference / first frame)

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

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

{ "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.

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

{ "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.

Audio cannot be used as the sole input. At least one reference image or video must also be included in the content array.

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

{ "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: 32 MiB (33,554,432 bytes). This is a hard platform limit on every Mesh endpoint, enforced at the edge — an oversized request is rejected before it reaches the API and returns a plain HTML 413 Request Entity Too Large page rather than a Mesh error envelope. See Rate Limits & Spend Caps.

Do not use Base64 encoding for large files — it inflates the payload by ~33%, so a file of ~24 MB already exceeds the 32 MiB request body limit on its own. Use a public URL instead; the per-file caps above are only reachable that way.

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,...).

Character consistency on Seedance 2.x

Seedance 2.0 and 2.5 screen reference material for likeness and copyright risk, and will decline a reference that looks like a real person. That screening is the reason a reference which “should” work sometimes produces a video ignoring it. For these models, Mesh registers your reference with the provider’s trusted asset library before generating, so a consistent character survives across shots. This is automatic — send the reference exactly as you would otherwise, as a public URL or a data URI, and Mesh handles registration. Three consequences worth knowing:

The first request using a new reference can return 422 with “still being prepared”. Registration is asynchronous on the provider’s side and has no guaranteed completion time. Retry the same request; the reference is recognised by content, so the retry reuses the in-flight registration rather than starting another one. Subsequent requests with the same image are immediate.

References are matched on content, not URL. The same image behind two different URLs — a re-signed link, a CDN variant — is one reference. Changing the URL of an image you have already used costs nothing. asset:// references are not accepted. If you have seen provider asset IDs elsewhere, they cannot be passed to Mesh; supply the reference as a URL and Mesh registers it under your organisation. Sending one returns 422.

By supplying a reference you confirm you have the rights to it and that it is not the likeness of a real person. Registered references are retained while you keep using them and are removed once unused. See the Terms of Service.

Seedance input support matrix

Input type	All Seedance models	Seedance 2.0 series only	Public URL	Base64
Text prompt	Yes	—	—	—
Image	Yes	—	Yes	Yes
Video	—	Yes	Yes	Yes
Audio	—	Yes (requires image or video)	Yes	Yes

Response

{ "id": "t-xxxxxxxxxxxxxxxx" }

Save the id to poll for status.

Example — text to video

curl
Python
Node.js

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"
  }'

import requests

response = requests.post(
    "https://api.meshapi.ai/v1/video/generations",
    headers={"Authorization": "Bearer rsk_your_key"},
    json={
        "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"
    }
)
task_id = response.json()["id"]
print(task_id)

const res = await fetch("https://api.meshapi.ai/v1/video/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer rsk_your_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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"
  })
});
const { id } = await res.json();
console.log(id);

Example — image to video

{
  "model": "byteplus/dreamina-seedance-2-0",
  "content": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.jpg" }
    },
    {
      "type": "text",
      "text": "The subject slowly turns and walks toward the camera"
    }
  ],
  "duration": 5,
  "ratio": "9:16"
}

Example — video with audio input

{
  "model": "byteplus/dreamina-seedance-2-0",
  "content": [
    {
      "type": "text",
      "text": "A product reveal with dramatic lighting"
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "https://example.com/background-music.mp3" }
    }
  ],
  "duration": 8,
  "generate_audio": false
}

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

Status	Meaning
`queued`	Task accepted, not yet started.
`running`	Generation in progress.
`succeeded`	Complete — `content.video_url` is populated.
`failed`	Error — check the `error` field.
`expired`	Task timed out before completing.
`cancelled`	Task was cancelled.

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

Field	Type	Description
`id`	string	Task ID.
`model`	string	Model ID used.
`status`	string	Current task status.
`content.video_url`	string	Downloadable video URL (when `succeeded`).
`content.last_frame_url`	string	Still image of the final frame (when `return_last_frame` was set).
`error.code`	string	Error code (when `failed`).
`error.message`	string	Human-readable error description (when `failed`).
`usage.completion_tokens`	integer	Tokens billed for the generation.
`usage.total_tokens`	integer	Total tokens (input + output).
`seed`	integer	Seed used for the generation.
`resolution`	string	Output resolution.
`ratio`	string	Aspect ratio.
`duration`	integer	Duration in seconds.
`frames`	integer	Frame count.
`framespersecond`	integer	Frames per second of the output.
`generate_audio`	boolean	Whether audio was generated.
`created_at`	integer	Unix timestamp of task creation.
`updated_at`	integer	Unix timestamp of last status update.

Example — polling until complete

Python
curl

import time
import requests

TASK_ID = "t-xxxxxxxxxxxxxxxx"
headers = {"Authorization": "Bearer rsk_your_key"}

while True:
    res = requests.get(
        f"https://api.meshapi.ai/v1/video/generations/{TASK_ID}",
        headers=headers
    ).json()

    status = res["status"]
    print(f"Status: {status}")

    if status == "succeeded":
        print("Video URL:", res["content"]["video_url"])
        break
    elif status in ("failed", "expired", "cancelled"):
        print("Error:", res.get("error"))
        break

    time.sleep(5)

# Poll until terminal
while true; do
  RESULT=$(curl -s "https://api.meshapi.ai/v1/video/generations/$TASK_ID" \
    -H "Authorization: Bearer rsk_your_key")
  STATUS=$(echo $RESULT | jq -r '.status')
  echo "Status: $STATUS"
  if [[ "$STATUS" == "succeeded" || "$STATUS" == "failed" || "$STATUS" == "expired" ]]; then
    echo $RESULT | jq
    break
  fi
  sleep 5
done

Succeeded response

{
  "id": "t-xxxxxxxxxxxxxxxx",
  "model": "byteplus/dreamina-seedance-2-0",
  "status": "succeeded",
  "content": {
    "video_url": "https://cdn.example.com/videos/generated.mp4",
    "last_frame_url": "https://cdn.example.com/videos/last-frame.jpg"
  },
  "usage": {
    "completion_tokens": 200,
    "total_tokens": 200
  },
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "frames": 150,
  "framespersecond": 30,
  "created_at": 1718000000,
  "updated_at": 1718000180
}

Failed response

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

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

Parameter	Type	Description
`status`	string (repeatable)	Filter by status. Multiple values combine with OR, e.g. `?status=running&status=succeeded`.
`model`	string (repeatable)	Filter by model ID. Multiple values combine with OR.
`created_after`	ISO 8601 datetime	Only include tasks created at or after this timestamp.
`created_before`	ISO 8601 datetime	Only include tasks created before this timestamp.
`limit`	integer 1–200	Page size (default 50).
`offset`	integer	Pagination offset (default 0).

Results are ordered by created_at descending (newest first).

Response

{
  "object": "list",
  "data": [
    {
      "id": "t-xxxxxxxxxxxxxxxx",
      "model": "byteplus/dreamina-seedance-2-0",
      "status": "succeeded",
      "created_at": 1718000000,
      "updated_at": 1718000180,
      "content": {
        "video_url": "https://cdn.example.com/videos/generated.mp4"
      }
    }
  ],
  "has_more": false,
  "total": 1,
  "limit": 50,
  "offset": 0
}

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

You pass "callback_url": "https://yourapp.example.com/webhooks/video" in the create request.
Mesh API intercepts the completion notification from the upstream provider, updates its database, and then forwards the completed task payload to your callback_url.
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}:

{
  "id": "t-xxxxxxxxxxxxxxxx",
  "model": "byteplus/dreamina-seedance-2-0",
  "status": "succeeded",
  "content": {
    "video_url": "https://cdn.example.com/videos/generated.mp4",
    "last_frame_url": "https://cdn.example.com/videos/last-frame.jpg"
  },
  "usage": {
    "completion_tokens": 200,
    "total_tokens": 200
  },
  "generate_audio": false,
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5
}

Handling the webhook

Your endpoint should:

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.
Identify the task from id in the payload.
Check status to decide what to do — download content.video_url on success, log or surface error on failure.

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/video", methods=["POST"])
def video_webhook():
    task = request.json
    task_id = task["id"]
    status = task["status"]

    if status == "succeeded":
        video_url = task["content"]["video_url"]
        # save or process the video
        print(f"Task {task_id} succeeded: {video_url}")
    elif status == "failed":
        error = task.get("error", {})
        print(f"Task {task_id} failed: {error.get('code')} — {error.get('message')}")
    elif status == "expired":
        print(f"Task {task_id} expired before completing")

    return jsonify({"ok": True}), 200

Webhook vs polling — when to use each

Approach	Best for
Webhook	Production apps, background pipelines — no polling overhead, event-driven.
Polling	Quick scripts, testing, environments where you can’t expose a public endpoint.

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:

Output type	Billing basis
Video only	`completion_tokens` from the usage response
Video + audio (`generate_audio: true`)	Higher per-token rate
Video with video input	Higher per-token rate

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

Error reference

HTTP status	Meaning
`200`	Task created or retrieved successfully.
`401`	Missing or invalid API key.
`402`	Insufficient balance or spend cap reached.
`422`	The model is not supported for video generation.
`429`	Rate limit exceeded.
`502`	Upstream provider error.
`503`	Video generation service temporarily unavailable.

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).

​Endpoints

​Create a Video Generation Task

​Request body

​Content items

​Text prompt

​Image input (reference / first frame)

​Video input (reference video)

​Audio input

​Input size limits

​Character consistency on Seedance 2.x

​Seedance input support matrix

​Response

​Example — text to video

​Example — image to video

​Example — video with audio input

​Get Task Status

​Task statuses

​Response fields

​Example — polling until complete

​Succeeded response

​Failed response

​List Tasks

​Query parameters

​Response

​Webhooks

​How it works

​Webhook payload

​Handling the webhook

​Webhook vs polling — when to use each

​Pricing

​Error reference

Endpoints

Create a Video Generation Task

Request body

Content items

Text prompt

Image input (reference / first frame)

Video input (reference video)

Audio input

Input size limits

Character consistency on Seedance 2.x

Seedance input support matrix

Response

Example — text to video

Example — image to video

Example — video with audio input

Get Task Status

Task statuses

Response fields

Example — polling until complete

Succeeded response

Failed response

List Tasks

Query parameters

Response

Webhooks

How it works

Webhook payload

Handling the webhook

Webhook vs polling — when to use each

Pricing

Error reference