Create a generation job

POST

api

generate

curl -X POST https://vidgen.id/api/v1/generate \
  -H "Authorization: Bearer vg_4b1a82f3c9d0e1f2a3b4c5d6e7f80912" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5-flash",
    "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    "parameters": { "duration": "5", "ratio": "16:9", "resolution": "720p" },
    "idempotencyKey": "order-4711-a39f2c7b"
  }'

const res = await fetch("https://vidgen.id/api/v1/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIDGEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2-5-flash",
    prompt: "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    parameters: { duration: "5", ratio: "16:9", resolution: "720p" },
    idempotencyKey: "order-4711-a39f2c7b",
  }),
});

console.log(res.status, await res.json());

res = requests.post(
    "https://vidgen.id/api/v1/generate",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "seedance-2-5-flash",
        "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
        "parameters": {"duration": "5", "ratio": "16:9", "resolution": "720p"},
        "idempotencyKey": "order-4711-a39f2c7b",
    },
)

print(res.status_code, res.json())

{
  "success": true,
  "job": {
    "id": "9f2c1d34-a8b7-4e0f-9a1b-2c3d4e5f6a7b",
    "status": "queued",
    "model": "seedance-2-5-flash",
    "category": "Video",
    "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    "creditsCharged": 3,
    "createdAt": "2026-11-04T09:12:44.000Z"
  },
  "queue": { "position": 2, "status": "queued" }
}

{
  "success": true,
  "job": {
    "id": "9f2c1d34-a8b7-4e0f-9a1b-2c3d4e5f6a7b",
    "status": "succeeded",
    "model": "seedance-2-5-flash",
    "category": "Video",
    "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    "result": { "url": "https://vidgen.id/api/media-proxy?token=..." },
    "creditsCharged": 3,
    "createdAt": "2026-11-04T09:12:44.000Z"
  },
  "queue": { "position": 0 },
  "idempotent": true
}

{
  "error": "Kredit akun tidak mencukupi. Pembuatan ini membutuhkan 10 kredit",
  "requiredCredits": 10,
  "currentCredits": 4
}

{
  "error": "Maksimal 2 proses generate bersamaan. Tunggu salah satunya selesai sebelum memulai yang baru.",
  "maxConcurrent": 2,
  "activeJobs": 2
}

{
  "error": "Parameter tidak valid: Durasi 60s tidak didukung Seedance 2.5 Flash. Pilihan: 20s.",
  "fields": ["Durasi 60s tidak didukung Seedance 2.5 Flash. Pilihan: 20s."]
}

Creates one generation job. Credits are deducted at this endpoint, and the request is answered before the result is ready.

Need the list of models you can put in the model field? Get it from GET /api/v1/models. The valid parameters values also depend on the model.

Authorizations

string

required

API key formatted Bearer vg_.... You can also use the x-api-key header.

Request body

string

required

Model id from the catalog, for example seedance-2-5-flash. Spellings with dots and hyphens are treated the same. A model that exists but is currently disabled is answered 409.

string

A description of what you want created. Required except for motion control models, which may leave it empty because the server fills in a neutral instruction. Maximum 2,500 characters for motion models.The prompt passes through content filtering first; sensitive words, public figures, or indications of abuse are removed before the request is forwarded. Some models sold openly without filtering are recognizable by their id (spicy, nsfw) and are not filtered.

object

default:"{}"

Output settings. Only recognized keys are processed; other keys are ignored without an error.

Show recognized properties

string

Duration in seconds, e.g. "5" or "30". A trailing s is accepted and stripped. Validated against capabilities.durations. Ignored on motion control models.

string

Resolution, e.g. "720p", "1080p", "1K", "2K", "4K". Validated against capabilities.resolutions.

string

Aspect ratio: "16:9", "9:16", "1:1", "4:3", "3:4", or "auto". aspect_ratio is accepted as an alias.

string

For image models that have capabilities.qualities (low, medium, high, max). Ignored if the model does not support it.

string

For image models that have capabilities.backgrounds (auto, transparent, opaque).

string

Output format; format is accepted as an alias. Only used if the model has capabilities.outputFormats.

string

What you do not want. Only forwarded if capabilities.supportsNegativePrompt.

string

Random seed for reproducible results. Only forwarded if capabilities.supportsSeed.

string

Motion control only: "image" (output ratio follows the character image) or "video" (output ratio follows the motion video). Other values are ignored.

array<object>

Input material: character images, products, or motion videos. Each object can be an asset from POST /api/v1/upload or a public URL.

Show reference object

string

Asset id from the upload endpoint. If present, this object is used as-is (also send url, file_url, and filename exactly as you received them).

string

A public media URL (http or https) that the server will download with a 20 second timeout. Download failures are answered 400.

string

"image", "video", or "audio". May be omitted — the server detects it from the file contents. Maximum counts per type depend on the model (defaults: 9 images / 1 video / 1 audio; image models allow 10 images and no video or audio).

string

File name in server storage. Follow the exact value from the upload response.

string

Minimum 8 characters. The same key returns the existing job with 200 and idempotent: true, without a second credit deduction. Below 8 characters, your value is ignored and the server generates its own key. See Idempotency.

curl -X POST https://vidgen.id/api/v1/generate \
  -H "Authorization: Bearer vg_4b1a82f3c9d0e1f2a3b4c5d6e7f80912" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5-flash",
    "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    "parameters": { "duration": "5", "ratio": "16:9", "resolution": "720p" },
    "idempotencyKey": "order-4711-a39f2c7b"
  }'

const res = await fetch("https://vidgen.id/api/v1/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIDGEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2-5-flash",
    prompt: "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    parameters: { duration: "5", ratio: "16:9", resolution: "720p" },
    idempotencyKey: "order-4711-a39f2c7b",
  }),
});

console.log(res.status, await res.json());

res = requests.post(
    "https://vidgen.id/api/v1/generate",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "seedance-2-5-flash",
        "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
        "parameters": {"duration": "5", "ratio": "16:9", "resolution": "720p"},
        "idempotencyKey": "order-4711-a39f2c7b",
    },
)

print(res.status_code, res.json())

Responses

boolean

true on every successful response.

object

required

The job object.

Hide job properties

string

required

The id to poll at GET /api/v1/jobs/{id}.

string

required

"queued" for a new job. Other values: dispatching, processing, succeeded, failed, cancelled.

string

Model id that was used.

string

"Video", "Image", or "Audio".

string

The prompt after content filtering. This is what was actually processed.

number

required

Credits deducted. 0 when the Unlimited quota covered it.

string (ISO 8601)

When the job was created, UTC.

object | null

Only populated on an idempotent replay of an already finished job; always null for a new job.

object

Queue information at the moment the request was made.

Show contents of queue

number

Position in the queue. 0 means it is being processed or the position is not reported.

string

Mirrors the job status, usually "queued".

boolean

Only present when the same key was already used and the original job is being returned.

{
  "success": true,
  "job": {
    "id": "9f2c1d34-a8b7-4e0f-9a1b-2c3d4e5f6a7b",
    "status": "queued",
    "model": "seedance-2-5-flash",
    "category": "Video",
    "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    "creditsCharged": 3,
    "createdAt": "2026-11-04T09:12:44.000Z"
  },
  "queue": { "position": 2, "status": "queued" }
}

{
  "success": true,
  "job": {
    "id": "9f2c1d34-a8b7-4e0f-9a1b-2c3d4e5f6a7b",
    "status": "succeeded",
    "model": "seedance-2-5-flash",
    "category": "Video",
    "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    "result": { "url": "https://vidgen.id/api/media-proxy?token=..." },
    "creditsCharged": 3,
    "createdAt": "2026-11-04T09:12:44.000Z"
  },
  "queue": { "position": 0 },
  "idempotent": true
}

{
  "error": "Kredit akun tidak mencukupi. Pembuatan ini membutuhkan 10 kredit",
  "requiredCredits": 10,
  "currentCredits": 4
}

{
  "error": "Maksimal 2 proses generate bersamaan. Tunggu salah satunya selesai sebelum memulai yang baru.",
  "maxConcurrent": 2,
  "activeJobs": 2
}

{
  "error": "Parameter tidak valid: Durasi 60s tidak didukung Seedance 2.5 Flash. Pilihan: 20s.",
  "fields": ["Durasi 60s tidak didukung Seedance 2.5 Flash. Pilihan: 20s."]
}

What you need to know

Why 202 and not 200?

Generation is asynchronous. 202 means the request was accepted and the queue entry is set up; you fetch the result later through the job id. The only 200 on this endpoint is an idempotent replay.

When are credits deducted and when do they come back?

They are deducted before the job is saved. If the job fails, the cancellation fails to save, or the queue is full, the credits are refunded automatically with a refund reason recorded in the account history. You do not need to build your own refund mechanism.

Can a request be safely repeated?

Yes, as long as you use the same idempotencyKey with a length of at least 8 characters. Without it, every retry is a new job with a new charge.

Extra fields in the body are ignored?

Yes. A body sending watermark: false or n: 2 produces no error, but also no effect. Only model, prompt, parameters, references, and idempotencyKey are read.

Limits that make this request get rejected

Two concurrent processes (Unlimited accounts only), 50 successful videos per day, the server queue being full, or the site being under maintenance. All of them use 429 or 503.

⌘I

curl -X POST https://vidgen.id/api/v1/generate \
  -H "Authorization: Bearer vg_4b1a82f3c9d0e1f2a3b4c5d6e7f80912" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5-flash",
    "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    "parameters": { "duration": "5", "ratio": "16:9", "resolution": "720p" },
    "idempotencyKey": "order-4711-a39f2c7b"
  }'

const res = await fetch("https://vidgen.id/api/v1/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIDGEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2-5-flash",
    prompt: "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    parameters: { duration: "5", ratio: "16:9", resolution: "720p" },
    idempotencyKey: "order-4711-a39f2c7b",
  }),
});

console.log(res.status, await res.json());

res = requests.post(
    "https://vidgen.id/api/v1/generate",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "seedance-2-5-flash",
        "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
        "parameters": {"duration": "5", "ratio": "16:9", "resolution": "720p"},
        "idempotencyKey": "order-4711-a39f2c7b",
    },
)

print(res.status_code, res.json())

{
  "success": true,
  "job": {
    "id": "9f2c1d34-a8b7-4e0f-9a1b-2c3d4e5f6a7b",
    "status": "queued",
    "model": "seedance-2-5-flash",
    "category": "Video",
    "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    "creditsCharged": 3,
    "createdAt": "2026-11-04T09:12:44.000Z"
  },
  "queue": { "position": 2, "status": "queued" }
}

{
  "success": true,
  "job": {
    "id": "9f2c1d34-a8b7-4e0f-9a1b-2c3d4e5f6a7b",
    "status": "succeeded",
    "model": "seedance-2-5-flash",
    "category": "Video",
    "prompt": "secangkir kopi di meja kayu, cahaya pagi, kamera dolly perlahan ke kanan",
    "result": { "url": "https://vidgen.id/api/media-proxy?token=..." },
    "creditsCharged": 3,
    "createdAt": "2026-11-04T09:12:44.000Z"
  },
  "queue": { "position": 0 },
  "idempotent": true
}

{
  "error": "Kredit akun tidak mencukupi. Pembuatan ini membutuhkan 10 kredit",
  "requiredCredits": 10,
  "currentCredits": 4
}

{
  "error": "Maksimal 2 proses generate bersamaan. Tunggu salah satunya selesai sebelum memulai yang baru.",
  "maxConcurrent": 2,
  "activeJobs": 2
}

{
  "error": "Parameter tidak valid: Durasi 60s tidak didukung Seedance 2.5 Flash. Pilihan: 20s.",
  "fields": ["Durasi 60s tidak didukung Seedance 2.5 Flash. Pilihan: 20s."]
}

Overview

Generate

Media

Catalog & account

Authorizations

Request body

Responses

What you need to know

​Authorizations

​Request body

​Responses

​What you need to know

Authorizations

Request body

Responses

What you need to know