Generate Endpoint - VicSee API Video & Image Generation

Create AI videos and images with VicSee's unified generate endpoint. Supports all models including Seedance 2.0, Veo 3.1, FLUX 2, and Nano Banana with async processing.

Create AI-generated content using a unified endpoint. Also available as agent tools via the VicSee MCP Server.

POST /api/v1/generate

Put every generation parameter inside the input object. A fully flat body — model, prompt and the parameters all at the top level, with no input key at all — is also accepted.

Do not mix the two. If input is present and parameters are sent at the top level, those top-level ones cannot be read, so the request is rejected with 422 MIXED_ENVELOPE naming the stray keys. Nothing is generated and no credits are used — fix the body and retry.

Two exceptions: model is always top-level, and prompt is accepted in either place — inside input or at the top level. If you send both, input.prompt wins. If you are building an agent, the simplest way to never think about this is the MCP Server: it takes flat parameters and builds the correct request for you.

Omitted parameters fall back to the model's default, which is not always the cheapest one. MiniMax H3 defaults to 2K, so a 15-second video with no resolution costs 600 credits instead of the 375 it would cost at 768P.

Send resolution and duration explicitly, and read the resolvedParams object returned by both POST /generate and GET /tasks/{id} — it lists the settings that were actually applied, so you never have to infer them from the credit charge.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token with your API key
Content-Type	Yes	Must be application/json

Body Parameters

Parameter	Type	Required	Description
model	string	Yes	The model to use. Call `GET /api/v1/models` for available IDs.
prompt	string	Yes*	Text description of what to generate. *Optional for upscale and some image-to-video models.
input	object	Yes	Wrapper holding all generation parameters (see below).

options is accepted as a legacy alias for input. New integrations should use input. Do not send both.

`input` parameters

Valid values are model-specific. Always check the GET /api/v1/models response for the exact options, requires, and accepts of the model you are calling.

Parameter	Type	Applies to	Description
duration	number	video	Video length in seconds. Range is model-specific (e.g. Seedance 2 Mini: 4–15).
resolution	string	video / image	e.g. `480p`, `720p`, `1080p` for video; `1K`, `2K`, `4K` for image.
aspect_ratio	string	most	Output aspect ratio, e.g. `16:9`, `9:16`, `1:1`.
image_urls	string[]	image-to-video, image-to-image	Source image(s). Each must be a public `http(s)` URL or a base64 `data:` URI. Aspect ratio 0.4–2.5 (width÷height), max 36 MP.
reference_image_urls	string[]	reference-to-video	Up to 7 reference images. Refer to them in the prompt as `@Image1`, `@Image2`, … Each image: aspect ratio 0.4–2.5 (width÷height), max 36 MP — wide-strip composites are rejected; use a 2×2 grid.
reference_video_urls	string[]	reference-to-video	Up to 3 reference videos (total ≤ 15s). Public `http(s)` URLs only.
reference_audio_urls	string[]	reference-to-video	Up to 3 reference audio clips (total ≤ 15s). Public `http(s)` URLs only.
audio	boolean	video	Generate synchronized native audio (default `true` where supported).

Example Request — text-to-video

curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-mini-text-to-video",
    "prompt": "A timelapse of a flower blooming",
    "input": {
      "duration": 15,
      "resolution": "480p",
      "aspect_ratio": "16:9"
    }
  }'

Example Request — reference-to-video

Pass references in reference_image_urls (and optionally reference_video_urls / reference_audio_urls), then refer to them positionally in the prompt.

curl -X POST https://vicsee.com/api/v1/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-mini-reference-to-video",
    "prompt": "@Image1 walking through a neon-lit street at night",
    "input": {
      "duration": 8,
      "resolution": "720p",
      "reference_image_urls": ["https://example.com/character.png"]
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "task_abc123",
    "model": "seedance-2-mini-text-to-video",
    "status": "processing",
    "creditsUsed": 143,
    "creditsRemaining": 1450,
    "createdAt": "2026-06-25T10:30:00.000Z"
  }
}

Response Fields

Field	Type	Description
id	string	Unique task ID for polling status
model	string	The model used
status	string	Task status: `pending`, `processing`, `completed`, or `failed`. The polling endpoint `GET /api/v1/tasks/{id}` reports `completed` on success and `failed` on failure.
creditsUsed	number	Credits consumed
creditsRemaining	number	Your remaining balance

Next Steps

Save the id from the response
Poll GET /api/v1/tasks/id for status updates
When status is completed, download your content

Request Errors

These codes are returned by POST /api/v1/generate when a request is rejected before a task is created. They arrive as an HTTP 4xx/5xx response with { "success": false, "error": { "code": ... } }. They are distinct from a task that is created and later fails during processing — that case returns HTTP 200 with status: "failed" (poll GET /api/v1/tasks/{id} for details).

Code	Description
MISSING_MODEL	No model specified
MISSING_PROMPT	No prompt provided
MISSING_IMAGE	Model requires `image_urls` (image-to-video / image-to-image)
MISSING_REFERENCE	Reference-to-video model requires at least one of `reference_image_urls`, `reference_video_urls`, `reference_audio_urls`
INVALID_INPUT_URL	A media input was not a public `http(s)` URL or base64 `data:` URI
INVALID_MODEL	Model does not exist
INVALID_DURATION	`duration` is out of range or not an allowed value for this model (e.g. Seedance 2.0 accepts 4-15s; Kling 2.6 accepts 5 or 10). The error `message` lists the allowed values. Returned before any task is created, so no credits are spent.
INSUFFICIENT_CREDITS	Not enough credits
RATE_LIMITED	Too many requests

Generate Endpoint - VicSee API Video & Image Generation

On this page