SeeGen AI API

Manage API Keys

Welcome to the SeeGen AI API — one API for cinematic video and high-fidelity image generation across multiple leading models.

API Playground Pricing

SeeGen AI is a unified generation API: one consistent set of endpoints to run multiple leading AI video and image models. Choose a model with the model parameter — authentication, task submission, status polling, and webhooks work the same way across all of them.

Currently available models:

Video — Seedance 2.0 Pro (sd2), Seedance 2.0 Fast (sd2-fast), Seedance 2.0 Mini (sd2-mini), Seedance 2.5 (sd2.5), HappyHorse 1.1 (happyhorse)
Image — GPT Image 2 (gpt-image-2), Nano Banana 2 (nano-banana-2), Nano Banana Pro (nano-banana-pro), Seedream 5.0 Lite (seedream-v5.0-lite), Seedream 5.0 Pro (seedream-v5.0-pro)

Base URL: https://seegen.ai/api/v1

Model: pass any alias above as the model field (e.g. sd2, gpt-image-2).

More than Seedance 2.0: HappyHorse 1.1, Nano Banana, ChatGPT Image, and more.
No subscription is required — pay as you go
Fast access to the latest models
24/7 customer support
Support for official model-related inquiries
Console access for developers
Open to both businesses and individual users

40% OFF

API Pack

$500$833

125,000 credits ($0.004/credit)

~781 5s videos

40% OFF

API-XL Pack

$2,000$3,332

500,000 credits ($0.004/credit)

~3,125 5s videos

Seedance 2.0 / Fast / Mini / 2.5 — cost calculation

Let out = output_seconds and in = the sum of ⌈duration⌉ of each input video (each rounded up, minimum out × 2/3). Seedance 2.5 follows the same calculation as Seedance 2.0. Each corresponding model base rate is multiplied by 1.5 and rounded before the task formula is applied (1080P is native on sd2.5, 2.5× its 720P rate); model-independent upscale add-ons remain +30 / +40 credits per output second for 2K / 4K (+20 for 1080P on sd2-fast / sd2-mini only).

	No video input	Include video input
sd2.5: 480P	30 × out	23 × (out + in)
sd2.5: 720P	60 × out	45 × (out + in)
sd2.5: 1080P (native)	150 × out	113 × (out + in)
sd2.5: 2K	(60 + 30) × out	45 × (out + in) + 30 × out
sd2.5: 4K	(60 + 40) × out	45 × (out + in) + 40 × out
sd2-pro: 480P	20 × out	15 × (out + in)
sd2-pro: 720P	40 × out	30 × (out + in)
sd2-pro: 1080P (native)	100 × out	75 × (out + in)
sd2-pro: 2K	(40 + 30) × out	30 × (out + in) + 30 × out
sd2-pro: 4K (native)	200 × out	150 × (out + in)
sd2-fast: 480P	16 × out	12 × (out + in)
sd2-fast: 720P	32 × out	24 × (out + in)
sd2-fast: 1080P	(32 + 20) × out	24 × (out + in) + 20 × out
sd2-fast: 2K	(32 + 30) × out	24 × (out + in) + 30 × out
sd2-fast: 4K	(32 + 40) × out	24 × (out + in) + 40 × out
sd2-mini: 480P	10 × out	7.5 × (out + in)
sd2-mini: 720P	20 × out	15 × (out + in)
sd2-mini: 1080P	(20 + 20) × out	15 × (out + in) + 20 × out
sd2-mini: 2K	(20 + 30) × out	15 × (out + in) + 30 × out
sd2-mini: 4K	(20 + 40) × out	15 × (out + in) + 40 × out

Note: sd2-pro 1080P and 4K are native official output (4K = 5× the 720P rate); sd2-pro 2K and all of sd2-fast / sd2-mini 1080P/2K/4K are upscaled by SeeGen AI. sd2.5 generates natively at 480P/720P/1080P (1080P = 2.5× the 720P rate, no upscale add-on) and uses automatic upscale for 2K/4K. Request any tier via outputResolution: "4k" (e.g. "2k" / "4k"; the gateway picks native vs upscale automatically — only the price and the Native label differ). sd2-mini is priced at 50% of sd2-pro — the lowest-cost tier. Seedance 2.5 uses Seedance 2.0's per-video duration rounding, minimum input-duration floor, and upscale calculation. Each corresponding model base rate is multiplied by 1.5 and rounded before task calculation (e.g. 1080P with video: 75 × 1.5 → 113). The model-independent 2K / 4K upscale add-ons stay at +30 / +40 credits per output second. If upscale fails, the completed task returns the 720P fallback without a partial credit refund.

sd2.5 480P, 4-second output without video input: 120 credits
sd2.5 720P, 5-second output without video input: 300 credits
sd2.5 720P, 5-second output + 3-second input video (4-second minimum input): 405 credits
sd2.5 1080P native, 5-second output without video input: 750 credits
sd2.5 1080P native, 5-second output + 5-second input video: 1,130 credits

happyhorse — credits per second

Output	Credits / sec	5s example
720P	32	160
1080P	60	300
2K	32 + 30	310
4K	32 + 40	360

Note: 2K / 4K upscale is added on top of the 720P base (it is not stacked with native 1080P). t2v / i2v / r2v share the same per-second rate — reference images are not billed.

🎉 Limited-time offer: 33% off all image generation — all image prices below are already discounted.

gpt-image-2 — credits per image

Resolution	Medium quality	High quality
1k	1015	4770
2k (default)	2335	84125
4k	4060	154230

Each task produces 1 image. Submit N tasks for N variants. Failed tasks refund credits automatically.

nano-banana-2 & nano-banana-pro — credits per image

Resolution	nano-banana-2	nano-banana-pro
1k	2030	4060
2k (default)	3045	4060
4k	4770	74110

Each task produces 1 image. Submit N tasks for N variants. Failed tasks refund credits automatically.

Seedream 5.0 — credits per image

Model / tier	Credits
Lite 2k / 4k (flat rate)	710
Pro 1k (default)	1015
Pro 2k	2030

Each task produces 1 image. Submit N tasks for N variants. Failed tasks refund credits automatically. Reference images are not billed separately.

Check your balance: GET /api/v1/account/credits

All API requests require a Bearer token in the Authorization header. You can create and manage API keys from your Account Settings.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://seegen.ai/api/v1/account/credits

Important: Your API key is shown only once at creation. Store it securely. You can create up to 10 API keys per account.

Generate a video in two steps: create a task, then poll for the result.

# 1. Create a text-to-video task
TASK_ID=$(curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sd2",
    "inputs": {
      "prompt": "A golden retriever running on the beach at sunset",
      "duration": "5s",
      "resolution": "1280x720"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask | jq -r '.taskId')

echo "Task created: $TASK_ID"

# 2. Poll for result
while true; do
  RESULT=$(curl -s -H "Authorization: Bearer $API_KEY" \
    "https://seegen.ai/api/v1/jobs/queryTask?taskId=$TASK_ID")
  STATUS=$(echo $RESULT | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then
    echo $RESULT | jq .
    break
  fi
  sleep 5
done

POST/api/v1/jobs/createTask

Create a new video generation task

GET/api/v1/jobs/queryTask

Query task status and result

GET/api/v1/account/credits

Check your credits balance

POST/api/v1/assets/upload

Upload an asset (image/video/audio) for review

GET/api/v1/assets/status

Query asset review status

GET/api/v1/assets/list

List your uploaded assets

POST/api/v1/upscale/create

Submit a standalone video upscale task (720p / 1080p / 2K / 4K)

GET/api/v1/upscale/query

Poll a standalone upscale task's status and result

Two model families generate video. Pick by mode + price; combine with the Pricing section to estimate cost.

Model	T2V	I2V	First–Last	Multi-Ref	R2V	Native 1080p	Native 4K	Audio	720p / 5s
sd2.5	✓	✓	✓	✓	—	✓	upscale	✓	300 credits
sd2	✓	✓	✓	✓	—	✓	✓	✓	200 credits
sd2-fast	✓	✓	✓	✓	—	upscale	upscale	✓	160 credits
sd2-mini	✓	✓	✓	✓	—	upscale	upscale	✓	100 credits
happyhorse	✓	✓	—	—	✓	✓	upscale	✓	160 credits

T2V = Text to Video · I2V = Image to Video (first frame) · First–Last = first + last keyframe · Multi-Ref = mixed image / video / audio references · R2V = 1–9 reference images with character markers

Generate a video from a text prompt. No images required.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sd2",
    "inputs": {
      "prompt": "A futuristic city with flying cars at night, neon lights reflecting on wet streets",
      "duration": "5s",
      "resolution": "1280x720"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the video to generate. Max 20000 chars.
duration	string	No	Video length: "4s" to "15s"; sd2.5 supports up to "30s" (default: "5s")
resolution	string	No	Aspect ratio via resolution. Options: auto (default), 720x720, 720x960, 960x720, 1280x720, 720x1280, 1280x540
outputResolution	string	No	Output resolution tier: "480p", "720p" (default), "1080p", "2k", or "4k". Native resolutions differ by model: Seedance 2.0 Pro: 480p/720p/1080p/4k; Seedance 2.0 Fast & Mini: 480p/720p; Seedance 2.5: 480p/720p/1080p. Higher tiers are automatically upscaled.
seed	int	No	Reproducibility seed: -1 or omit for random; 0–2147483647 for fixed.
generateAudio	boolean	No	Whether to synthesize a synced audio track. Default true; pass false for silent video.

Animate a static image into a video. Provide one image URL as the starting frame.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sd2",
    "inputs": {
      "urls": ["https://example.com/photo.jpg"],  // or "asset://asset-20260326-abc123"
      "prompt": "The woman slowly turns her head and smiles",
      "duration": "5s"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Parameter	Type	Required	Description
urls	string[]	Yes	Array with one image URL (the source frame). Supports both HTTP URLs and asset references (e.g. "asset://asset-20260326-abc123")
prompt	string	No	Text description of the desired motion
duration	string	No	Video length: "4s" to "15s"; sd2.5 supports up to "30s" (default: "5s")
outputResolution	string	No	Output resolution tier: "480p", "720p" (default), "1080p", "2k", or "4k". Native resolutions differ by model: Seedance 2.0 Pro: 480p/720p/1080p/4k; Seedance 2.0 Fast & Mini: 480p/720p; Seedance 2.5: 480p/720p/1080p. Higher tiers are automatically upscaled.
seed	int	No	Reproducibility seed: -1 or omit for random; 0–2147483647 for fixed.
generateAudio	boolean	No	Whether to synthesize a synced audio track. Default true; pass false for silent video.

Define the starting and ending frames, and the model generates the transition between them. Uses videoInputMode: "keyframe".

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sd2",
    "inputs": {
      "urls": [
        "https://example.com/first-frame.jpg",
        "https://example.com/last-frame.jpg"
      ],
      "prompt": "Smooth camera transition from day to night",
      "duration": "5s",
      "videoInputMode": "keyframe"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Parameter	Type	Required	Description
urls	string[]	Yes	Array with exactly 2 image URLs: [first_frame, last_frame]. Supports both HTTP URLs and asset references (e.g. "asset://asset-20260326-abc123")
videoInputMode	string	Yes	Must be "keyframe"
prompt	string	No	Text description guiding the transition
duration	string	No	Video length: "4s" to "15s"; sd2.5 supports up to "30s" (default: "5s")
outputResolution	string	No	Output resolution tier: "480p", "720p" (default), "1080p", "2k", or "4k". Native resolutions differ by model: Seedance 2.0 Pro: 480p/720p/1080p/4k; Seedance 2.0 Fast & Mini: 480p/720p; Seedance 2.5: 480p/720p/1080p. Higher tiers are automatically upscaled.
seed	int	No	Reproducibility seed: -1 or omit for random; 0–2147483647 for fixed.
generateAudio	boolean	No	Whether to synthesize a synced audio track. Default true; pass false for silent video.

Use multiple reference images, videos, and audio files to guide generation. Uses videoInputMode: "reference". For sd2.5 this is the default reference sub-task; see Video Edit & Extend below to edit or continue an existing video instead.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sd2",
    "inputs": {
      "urls": [
        "https://example.com/ref1.jpg",
        "https://example.com/ref2.jpg"
      ],
      "videoUrls": ["asset://asset-motion-video"],
      "audioUrls": ["https://example.com/audio.mp3"],
      "prompt": "Character walks through a garden",
      "duration": "5s",
      "videoInputMode": "reference",
      "resolution": "1280x720"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Parameter	Type	Required	Description
urls	string[]	No	Reference image URLs (max 9). Supports both HTTP URLs and asset references (e.g. "asset://asset-20260326-abc123")
videoUrls	string[]	No	Reference video asset:// URIs — upload via /api/v1/assets/upload first; external URLs are rejected. sd2: max 3 videos, each ≤15s. sd2.5: up to 10 videos, each 2–30s and ≤200MB, total reference duration ≤30s, 480p–4K inputs supported.
audioUrls	string[]	No	Reference audio inputs. sd2 / sd2-fast / sd2-mini: up to 3 audio files, each 2–15s, total ≤15s — audio cannot be the only reference on these models (add at least one image or video). sd2.5: up to 10 files, ≤15MB and 2–30s each, total ≤30s, and audio-only input is supported.
videoInputMode	string	Yes	Must be "reference"
prompt	string	No	Text description
duration	string	No	Video length: "4s" to "15s"; sd2.5 supports up to "30s" (default: "5s")
resolution	string	Yes	Required for reference mode. Options: 720x720, 720x960, 960x720, 1280x720, 720x1280, 1280x540
outputResolution	string	No	Output resolution tier: "480p", "720p" (default), "1080p", "2k", or "4k". Native resolutions differ by model: Seedance 2.0 Pro: 480p/720p/1080p/4k; Seedance 2.0 Fast & Mini: 480p/720p; Seedance 2.5: 480p/720p/1080p. Higher tiers are automatically upscaled.
seed	int	No	Reproducibility seed: -1 or omit for random; 0–2147483647 for fixed.
generateAudio	boolean	No	Whether to synthesize a synced audio track. Default true; pass false for silent video.

Reference Constraints

Max 9 images, 3 videos, 3 audio files
Max 12 total files across all types
Each video/audio must be ≤ 15 seconds
Images must be at least 400px on the shortest side
sd2.5: max 30 images, 10 videos, 10 audio files, and 50 total; video and audio totals are each ≤ 30 seconds

sd2.5 splits reference-based generation into three sub-tasks. Omit mode for ordinary reference generation, set mode: "edit" to edit an existing video, or mode: "extend" to continue one. Both require at least one video in videoUrls and always output the source video's aspect ratio.

Put the video you want to operate on first in videoUrls and refer to it as "Video 1" in your prompt. edit forces the output length to match that first (source) video, which must be 4–30s, so any duration you send is ignored; billing uses the source-video duration as the output duration, plus all reference videos as input. extend accepts 1–3 clips stitched in order, and the duration you request is the output length of this generation (unrelated to the source length) — billed like ordinary reference generation.

The 2.0-family models (sd2 / sd2-fast / sd2-mini) also accept mode: "edit" and mode: "extend": they infer the operation from your prompt (describe the edit or continuation explicitly), the aspect ratio follows the source video, and duration stays under your control with ordinary billing.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sd2.5",
    "inputs": {
      "mode": "edit",
      "videoUrls": ["asset://asset-source-video"],
      "urls": ["https://example.com/annotation-at-1.2s.png"],
      "source_frame_timestamps_ms": [1200],
      "prompt": "Replace the marked object with a red umbrella",
      "outputResolution": "720p"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Parameter	Type	Required	Description
mode	string	No	"edit" or "extend". Omit for ordinary reference generation.
videoUrls	string[]	Yes	At least one video; the first is the source ("Video 1") — edit output length and billing follow it. Later videos are extra references (edit) or additional clips stitched in order (extend, max 3).
urls	string[]	No	Optional annotation/reference images.
source_frame_timestamps_ms	number[]	No	mode "edit" only. One non-negative source-video timestamp in milliseconds per image in urls.
outputResolution	string	No	Output resolution tier: "480p", "720p" (default), "1080p", "2k", or "4k". Native resolutions differ by model: Seedance 2.0 Pro: 480p/720p/1080p/4k; Seedance 2.0 Fast & Mini: 480p/720p; Seedance 2.5: 480p/720p/1080p. Higher tiers are automatically upscaled.

Complete reference of all inputs parameters for the sd2 / sd2-fast / sd2-mini / sd2.5 models.

Parameter	Type	Required	Description
prompt	string	No	Text description (required for text-to-video, optional for other modes). Max 20000 chars.
urls	string[]	No	Image URLs. Supports both HTTP URLs and asset references (e.g. "asset://asset-20260326-abc123"). Maps to uploadedUrls internally.
videoUrls	string[]	No	Video reference asset:// URIs (reference mode only). Must be uploaded via /api/v1/assets/upload first — external URLs are rejected.
audioUrls	string[]	No	Audio reference URLs (reference mode only). Audio-only input is supported on sd2.5; sd2 / sd2-fast / sd2-mini require at least one image or video alongside audio.
duration	string	No	"4s" to "15s" normally; sd2.5 supports up to "30s". Default: "5s"
resolution	string	No	Aspect ratio: auto (default) \| 720x720 \| 720x960 \| 960x720 \| 1280x720 \| 720x1280 \| 1280x540
outputResolution	string	No	Output resolution tier: "480p", "720p" (default), "1080p", "2k", or "4k". Native resolutions differ by model: Seedance 2.0 Pro: 480p/720p/1080p/4k; Seedance 2.0 Fast & Mini: 480p/720p; Seedance 2.5: 480p/720p/1080p. Higher tiers are automatically upscaled.
videoInputMode	string	No	"keyframe" (default) or "reference"
mode	string	No	Reference-mode sub-task (all Seedance models): omit for ordinary reference generation, "edit" to edit the first video in videoUrls, "extend" to continue 1-3 clips. See Video Edit & Extend.
source_frame_timestamps_ms	number[]	No	sd2.5 Video Edit only: one non-negative millisecond timestamp per annotation image.
seed	int	No	Random seed for reproducibility. -1 or omit for server-random. Same seed + same inputs yields a closely-matched output (not bit-identical due to GPU non-determinism). Range: -1 to 2147483647.
generateAudio	boolean	No	Whether to synthesize an audio track (speech, SFX, background music) synced to the video. Default true. Set false to produce a silent video — slightly faster, useful if you plan to dub separately.
bitrateMode	string	No	Output bitrate tier at the same resolution: "standard" (default) or "high". "high" preserves more detail and reduces banding / blocking at ~3-5× the file size — it does not change resolution or price.
upscaleResolution	string	No	(Deprecated) Legacy split field, still accepted for backward compatibility. New integrations should use outputResolution, which now takes "2k" / "4k" directly. If both are sent, upscaleResolution takes precedence — except on models with native 1080p (Seedance2 Pro / Seedance 2.5), where upscaleResolution:"1080p" resolves to native 1080p (billed at the native rate).

Top-level request fields: model (required), inputs (required), callBackUrl (optional webhook URL).

Assets are images, videos, and audio files that go through a review process before they can be used in video generation tasks. Upload an asset, wait for it to become ACTIVE, then use its asset:// URL in your tasks.

Note: Real human image and video assets require official review, usually completed within seconds. Once approved, they can be used directly as references. Without review, generation may fail.

Two ways to upload: send a local file directly (multipart/form-data), or submit a publicly accessible HTTPS URL. Either way the asset is processed and reviewed automatically.

Method A — direct file upload (multipart/form-data)

Send a local file with no image host required. The media type is detected from the file's bytes (the filename extension is not trusted). Allowed: images (jpg/png/webp/gif/bmp/tiff/heic), videos (mp4/mov), audio (wav/mp3). Max 50MB per file (image ≤30MB, video ≤50MB, audio ≤15MB).

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/path/to/photo.jpg" \
  -F "name=my-photo" \
  https://seegen.ai/api/v1/assets/upload

Parameter	Type	Required	Description
file	file	Yes	The local file (multipart form field). Media type is detected from content.
name	string	No	Asset name (max 64 characters)

Method B — by URL (application/json)

If the file is already hosted at a public HTTPS URL.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/photo.jpg",
    "type": "IMAGE",
    "name": "my-photo"
  }' \
  https://seegen.ai/api/v1/assets/upload

Parameter	Type	Required	Description
url	string	Yes	Publicly accessible HTTPS URL of the file to upload
type	string	Yes	"IMAGE", "AUDIO", or "VIDEO"
name	string	No	Asset name (max 64 characters)

{
  "assetId": 123,
  "volcAssetId": "asset-20260326-abc123",
  "type": "IMAGE",
  "status": "PROCESSING",
  "failReason": null,
  "url": "https://example.com/photo.jpg",
  "name": "my-photo",
  "createdAt": 1711234567890
}

Poll an asset's review status. When status is PROCESSING, the endpoint automatically checks for updates from the review system.

# Query by asset ID (numeric)
curl -H "Authorization: Bearer $API_KEY" \
  "https://seegen.ai/api/v1/assets/status?assetId=123"

# Query by volcAssetId (string)
curl -H "Authorization: Bearer $API_KEY" \
  "https://seegen.ai/api/v1/assets/status?assetId=asset-20260326-abc123"

Asset Status Values

PROCESSING — under review, not yet usable
ACTIVE — review passed, ready for use in tasks
FAILED — review failed, check failReason

List your uploaded assets with optional filtering by type and status. Supports cursor-based pagination.

# List all assets
curl -H "Authorization: Bearer $API_KEY" \
  "https://seegen.ai/api/v1/assets/list"

# Filter by type and status
curl -H "Authorization: Bearer $API_KEY" \
  "https://seegen.ai/api/v1/assets/list?type=IMAGE&status=ACTIVE&limit=10"

# Paginate with cursor
curl -H "Authorization: Bearer $API_KEY" \
  "https://seegen.ai/api/v1/assets/list?cursor=100&limit=20"

Parameter	Type	Required	Description
type	string	No	Filter by type: "IMAGE", "AUDIO", or "VIDEO"
status	string	No	Filter by status: "NONE", "PROCESSING", "ACTIVE", or "FAILED"
cursor	number	No	Cursor for pagination (use nextCursor from previous response)
limit	number	No	Items per page, 1-50 (default: 20)

{
  "items": [
    {
      "assetId": 123,
      "volcAssetId": "asset-20260326-abc123",
      "type": "IMAGE",
      "status": "ACTIVE",
      "failReason": null,
      "url": "https://example.com/photo.jpg",
      "name": "my-photo",
      "width": 1920,
      "height": 1080,
      "size": 245000,
      "duration": null,
      "createdAt": 1711234567890
    }
  ],
  "nextCursor": 122
}

Once an asset is ACTIVE, use its volcAssetId with the asset:// protocol in your task's URLs:

{
  "model": "sd2",
  "inputs": {
    "urls": ["asset://asset-20260326-abc123"],
    "prompt": "The person slowly looks up and smiles",
    "duration": "5s"
  }
}

An alternative video generation model from Alibaba DashScope. Supports three modes: text-to-video, first-frame image-to-video, and reference-to-video (1–9 reference images fused per prompt; refer to subjects with character1, character2, … in the prompt). HappyHorse 1.1 does not support last-frame, reference video, or reference audio. Model name: happyhorse.

No asset review required — you can use public HTTPS image URLs directly, or pass asset:// references from the asset library (resolved back to the original R2 URL automatically).

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse",
    "inputs": {
      "prompt": "A panda DJ at a beach party, smoky sunset",
      "duration": "5s",
      "outputResolution": "720p",
      "ratio": "16:9"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse",
    "inputs": {
      "urls": ["https://example.com/panda.jpg"],
      "prompt": "The panda blinks and smiles",
      "duration": "5s",
      "outputResolution": "1080p"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Pass videoWorkflowTab: "multi-reference" with 1–9 reference image URLs to fuse multiple subjects into a single output. Reference each image in the prompt with character1, character2, … (matching the order of urls). Aspect ratio is controlled by the ratio field (no first frame to drive it from).

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse",
    "inputs": {
      "videoWorkflowTab": "multi-reference",
      "urls": [
        "https://example.com/character.jpg",
        "https://example.com/folding-fan.jpg",
        "https://example.com/earrings.jpg"
      ],
      "prompt": "A woman in red character1 opening folding fan character2, with tassel earrings character3 swinging",
      "duration": "5s",
      "outputResolution": "720p",
      "ratio": "16:9"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Complete reference of all inputs parameters for the happyhorse model.

Parameter	Type	Required	Description
prompt	string	No	Text description. Required for text-to-video and reference-to-video; optional for image-to-video. Max 5000 non-CJK chars or 2500 CJK chars (upstream auto-truncates beyond). In r2v use character1/character2/… to refer to the N-th reference image.
urls	string[]	No	t2v: omit. i2v: exactly 1 URL (used as the first frame). r2v: 1–9 URLs. Supports public HTTPS URLs and asset references (e.g. "asset://asset-20260326-abc123").
videoWorkflowTab	string	No	Set to "multi-reference" to enable reference-to-video mode (must be combined with 1+ urls). Omit for text-to-video / image-to-video.
duration	string	No	"3s" to "15s" (default "5s").
outputResolution	string	No	"720p" (default) or "1080p".
ratio	string	No	"16:9" / "9:16" / "1:1" / "4:3" / "3:4". Used for text-to-video and reference-to-video — image-to-video aspect is inferred from the first frame.
seed	int	No	0 to 2147483647. Leave blank for a random seed.

Image Requirements (i2v / r2v)

Shortest side ≥ 300px
Aspect ratio between 1:2.5 and 2.5:1
Formats: JPEG, JPG, PNG, BMP, WEBP
Max file size 10MB per image (r2v: each of the 1–9 inputs)

Image models take a prompt (and optionally reference images) and return one image per task. Each request is billed per image using the selected model's tier (or a flat rate for Seedream Lite). Failed tasks are refunded automatically. There is no batch parameter — to generate multiple variations, call createTask once per image.

Model	T2I	I2I (Edit)	Multi-Ref	Max Resolution	2k / medium
gpt-image-2	✓	✓	up to 10	4k	see Pricing
nano-banana-2	✓	✓	up to 10	4k	see Pricing
nano-banana-pro	✓	✓	up to 10	4k	see Pricing
seedream-v5.0-lite	✓	✓	up to 10	4k	flat rate
seedream-v5.0-pro	✓	✓	up to 10	2k	see Pricing

OpenAI's GPT Image 2 model for high-quality text-to-image and image-to-image editing. One workflow handles both modes — pass urls to switch into edit mode automatically. Output is delivered via R2 in the format you request (PNG / JPEG / WEBP). Model name: gpt-image-2.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "inputs": {
      "prompt": "A neon-lit cyberpunk alley at midnight, photoreal",
      "quality": "medium",
      "resolution": "2k",
      "aspectRatio": "16:9"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Pass 1–10 reference images via urls. The model will use them as visual context for the edit described in prompt.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "inputs": {
      "urls": ["https://example.com/portrait.jpg"],
      "prompt": "Restyle as oil painting",
      "quality": "medium",
      "resolution": "1k",
      "aspectRatio": "1:1"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Complete reference of all inputs parameters for the gpt-image-2 model.

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the image to generate, or the edit to apply when urls is provided.
urls	string[]	No	Reference image URLs for image-to-image (edit) mode (1–10 images). Omit for text-to-image. Public HTTPS URLs accepted.
quality	string	No	"medium" / "high". Default: "medium". Credits scale by tier (see Pricing).
resolution	string	No	"1k" / "2k" / "4k". Default: "2k". Credits scale by tier (see Pricing).
aspectRatio	string	No	"1:1" / "16:9" / "9:16" / "4:3" / "3:4". Default: "1:1".
outputFormat	string	No	"png" / "jpeg" / "webp". Default: "png".

Input Image Requirements (image-to-image mode)

Up to 10 reference images per task
Max file size 50 MB per image
Shortest side ≥ 256px
Aspect ratio between 1:3 and 3:1
Formats: JPEG, JPG, PNG, WEBP

Credits per image scale by resolution and quality — see the Pricing section for the full table.

Nano Banana 2 is a high-fidelity image model with broader aspect-ratio coverage than gpt-image-2 — adds portrait/landscape presets (3:2, 2:3, 4:5, 5:4) and cinematic 21:9. One workflow handles both modes — pass urls to switch into edit mode automatically. Model name: nano-banana-2.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "inputs": {
      "prompt": "A neon-lit cyberpunk alley at midnight, photoreal",
      "resolution": "2k",
      "aspectRatio": "16:9"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Pass 1–10 reference images via urls. The model will use them as visual context for the edit described in prompt.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "inputs": {
      "urls": ["https://example.com/portrait.jpg"],
      "prompt": "Restyle as oil painting",
      "resolution": "2k",
      "aspectRatio": "1:1"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Complete reference of all inputs parameters for the nano-banana-2 model.

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the image to generate, or the edit to apply when urls is provided.
urls	string[]	No	Reference image URLs for image-to-image (edit) mode (1–10 images). Omit for text-to-image. Public HTTPS URLs accepted.
resolution	string	No	"1k" / "2k" / "4k". Default: "2k". Credits scale by tier (see Pricing).
aspectRatio	string	No	"1:1" / "16:9" / "9:16" / "4:3" / "3:4" / "3:2" / "2:3" / "4:5" / "5:4" / "21:9". Default: "1:1".

Input Image Requirements (image-to-image mode)

Up to 10 reference images per task
Max file size 50 MB per image
Shortest side ≥ 256px
Aspect ratio between 1:3 and 3:1
Formats: JPEG, JPG, PNG, WEBP

Credits per image scale by resolution — see the Pricing section for the full table.

Nano Banana Pro is a high-fidelity image model with broader aspect-ratio coverage than gpt-image-2 — adds portrait/landscape presets (3:2, 2:3, 4:5, 5:4) and cinematic 21:9. One workflow handles both modes — pass urls to switch into edit mode automatically. Model name: nano-banana-pro.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "inputs": {
      "prompt": "A neon-lit cyberpunk alley at midnight, photoreal",
      "resolution": "2k",
      "aspectRatio": "16:9"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Pass 1–10 reference images via urls. The model will use them as visual context for the edit described in prompt.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "inputs": {
      "urls": ["https://example.com/portrait.jpg"],
      "prompt": "Restyle as oil painting",
      "resolution": "2k",
      "aspectRatio": "1:1"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Complete reference of all inputs parameters for the nano-banana-pro model.

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the image to generate, or the edit to apply when urls is provided.
urls	string[]	No	Reference image URLs for image-to-image (edit) mode (1–10 images). Omit for text-to-image. Public HTTPS URLs accepted.
resolution	string	No	"1k" / "2k" / "4k". Default: "2k". Credits scale by tier (see Pricing).
aspectRatio	string	No	"1:1" / "16:9" / "9:16" / "4:3" / "3:4" / "3:2" / "2:3" / "4:5" / "5:4" / "21:9". Default: "1:1".

Input Image Requirements (image-to-image mode)

Up to 10 reference images per task
Max file size 50 MB per image
Shortest side ≥ 256px
Aspect ratio between 1:3 and 3:1
Formats: JPEG, JPG, PNG, WEBP

Credits per image scale by resolution — see the Pricing section for the full table.

Fast text-to-image and image-to-image generation at 2K or 4K with 15 aspect ratios. Model name: seedream-v5.0-lite.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v5.0-lite",
    "inputs": {
      "prompt": "A cinematic product photograph, soft studio light",
      "resolution": "2k",
      "aspectRatio": "1:1"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v5.0-lite",
    "inputs": {
      "prompt": "Restyle the references as a premium fashion campaign",
      "urls": ["https://example.com/reference.png"],
      "resolution": "4k",
      "aspectRatio": "3:4"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Parameter	Type	Required	Description
prompt	string	Yes	Image description or edit instruction.
urls	string[]	No	1–10 public HTTPS reference image URLs. Omit for text-to-image.
resolution	string	No	"2k" or "4k". Default: "2k".
aspectRatio	string	No	"1:1", "1:2", "2:1", "1:3", "3:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "9:21", or "21:9".

High-fidelity generation and editing at 1K or 2K. Model name: seedream-v5.0-pro.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v5.0-pro",
    "inputs": {
      "prompt": "Editorial portrait with dramatic rim lighting",
      "resolution": "2k",
      "aspectRatio": "3:4"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v5.0-pro",
    "inputs": {
      "prompt": "Turn the reference into a cinematic poster",
      "urls": ["https://example.com/reference.png"],
      "resolution": "2k",
      "aspectRatio": "1:2"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

Parameter	Type	Required	Description
prompt	string	Yes	Image description or edit instruction.
urls	string[]	No	1–10 public HTTPS reference image URLs. Omit for text-to-image.
resolution	string	No	"1k" or "2k". Default: "1k". 4k is not supported.
aspectRatio	string	No	"1:1", "1:2", "2:1", "1:3", "3:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "9:21", or "21:9".

POST /api/v1/upscale/create

# source.url accepts ANY https video URL — your own CDN, OR a file you first
# uploaded to us via /api/v1/assets/upload (pass the r2Url it returns). No need
# to declare which: we detect it. External URLs are validated; our own are trusted.
curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "url", "url": "https://your-cdn.com/video.mp4" },
    "targetResolution": "2k",
    "callBackUrl": "https://your-server.com/webhook"
  }' \
  https://seegen.ai/api/v1/upscale/create

Parameter	Type	Required	Description
source.type	string	Yes	Use "url" for any source. ("uploadId" is a legacy alias kept for backward compatibility.)
source.url	string	No	With type="url". Any https video URL — your own CDN, or the r2Url returned by /api/v1/assets/upload. For external URLs, http and private/internal IPs are rejected (SSRF guard); URLs on our own asset host skip that check.
source.r2Url	string	No	Legacy — only with type="uploadId" (backward compat). New integrations should use type="url".
targetResolution	string	Yes	"720p", "1080p", "2k", or "4k". Must be higher than the source resolution.
callBackUrl	string	No	Webhook URL invoked once on terminal state (completed or failed).

{
  "taskId": "n770mo4sh6rpi690ff3gwymx",
  "orderId": "ord_2026...",
  "status": "validating"
}

GET /api/v1/upscale/query?taskId=...

Status progresses validating → processing → completed / failed.

curl -H "Authorization: Bearer $API_KEY" \
  "https://seegen.ai/api/v1/upscale/query?taskId=n770mo4sh6rpi690ff3gwymx"

{
  "taskId": "n770mo4sh6rpi690ff3gwymx",
  "status": "completed",
  "targetResolution": "2k",
  "creditsConsumed": 900,
  "result": {
    "url": "https://static.seegen.ai/standalone-upscale/results/...mp4",
    "probedDurationSeconds": 30,
    "probedSourceResolution": "1280x720"
  },
  "error": null,
  "createdAt": "2026-04-29T01:23:45.000Z",
  "finishedAt": "2026-04-29T01:35:01.000Z"
}

{
  "taskId": "n770mo4sh6rpi690ff3gwymx",
  "status": "failed",
  "creditsConsumed": null,
  "result": null,
  "error": {
    "code": "SOURCE_RESOLUTION_TOO_HIGH",
    "message": "Source 3840x2160 is not below target 4k"
  }
}

Limits

Source: https URL or your previously uploaded R2 URL
Duration up to 600 s (clips under 5 s are billed as 5 s)
File size ≤ 200 MB
Format: MP4 / MOV / WebM
Source resolution must be lower than target

Common errors you can act on. Other failures return a self-explanatory message field — read that before assuming the code is one of these.

Code	Meaning
INVALID_URL	URL is malformed or not https
URL_NOT_REACHABLE	Couldn't fetch the URL — check it's public and reachable
UNSUPPORTED_MEDIA_TYPE	File is not a video, or not in MP4 / MOV / WebM
FILE_TOO_LARGE	Source exceeds 200 MB
DURATION_EXCEEDS_LIMIT	Source longer than 600 s
SOURCE_RESOLUTION_TOO_HIGH	Source already at or above target — pick a higher target
INSUFFICIENT_CREDITS	Not enough credits — top up and retry

Instead of polling, you can provide a callBackUrl to receive results automatically when a task completes or fails.

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sd2",
    "callBackUrl": "https://your-server.com/webhook/callback",
    "inputs": {
      "prompt": "A cat playing piano",
      "duration": "5s"
    }
  }' \
  https://seegen.ai/api/v1/jobs/createTask

When the task finishes, we send a POST request to your URL with the same format as the queryTask response:

// POST to your callBackUrl
{
  "taskId": "task_abc123",
  "model": "sd2",
  "status": "COMPLETED",
  "creditsUsed": 200,
  "output": [
    {
      "url": "https://static.seegen.ai/videos/result.mp4",
      "width": 1280,
      "height": 720
    }
  ],
  "error": null,
  "createTime": 1711234567890,
  "completeTime": 1711234612345
}

Retry Policy: If your endpoint returns a non-2xx status, we retry up to 3 times with increasing delays (1s, 5s, 30s).

// 200 OK
{ "taskId": "task_abc123" }

{
  "taskId": "task_abc123",
  "model": "sd2",
  "status": "COMPLETED",     // "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED"
  "creditsUsed": 200,
  "output": [                // null when status is not "COMPLETED"
    {
      "url": "https://static.seegen.ai/videos/result.mp4",
      "width": 1280,
      "height": 720
    }
  ],
  "error": null,             // error message when status is "FAILED"
  "createTime": 1711234567890,
  "completeTime": 1711234612345
}

{
  "credits": 5000,
  "availableCredits": 4800
}

Status Code	Meaning	Action
400	Invalid parameters	Check the error message and fix your request
401	Invalid or missing API key	Check your Authorization header format
402	Insufficient credits	Purchase more credits at seegen.ai
403	Access denied	You can only query your own tasks
404	Task not found	Verify the taskId is correct
429	Concurrency limit (3 tasks)	Wait for existing tasks to complete
500	Internal server error	Retry after a few seconds

Seedance requests are checked against the upstream contract before any credits are charged. When a check fails, createTask returns { "message": "...", "code": "..." } with HTTP 400 and no task is created. The message says exactly which limit was hit and how to fix it.

Parameter	Type	Required	Description
EMPTY_CONTENT	code	No	No prompt and no reference image / video / audio.
AUDIO_ONLY_NOT_SUPPORTED	code	No	Audio is the only reference on sd2 / sd2-fast / sd2-mini. Add an image or video, or use sd2.5 (audio-only supported).
DURATION_OUT_OF_RANGE	code	No	duration is not an integer within the model range (sd2 family "4s"–"15s", sd2.5 "4s"–"30s").
EDIT_SOURCE_VIDEO_REQUIRED / EXTEND_SOURCE_VIDEO_REQUIRED	code	No	mode "edit" / "extend" was requested without a video in videoUrls.
EDIT_SOURCE_DURATION_INVALID	code	No	sd2.5 Video Edit: a video in the request is shorter than 4s or longer than 30s (ARK applies 4–30s to every video of an edit task).
TOO_MANY_REFERENCES	code	No	More reference images / videos / audio clips than the model accepts (sd2 family 9 / 3 / 3, sd2.5 30 / 10 / 10; extend ≤3 videos).
REFERENCE_VIDEO_DURATION_INVALID	code	No	A reference video exceeds the per-clip maximum (sd2 family 15s, sd2.5 30s) or the total reference duration exceeds the cap (15s / 30s).
ASSET_NOT_FOUND / EXTERNAL_URL / READ_TIMEOUT / READ_FAILED	code	No	A videoUrls entry could not be resolved to one of your uploaded assets, or its duration could not be read.

Complete workflow: upload an asset, wait for review, create a task with the approved asset, and poll for the result.

const API_KEY = process.env.API_KEY;
const BASE = "https://seegen.ai/api/v1";
const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Upload asset and wait for review
// (To upload a LOCAL file instead of a URL, POST multipart/form-data with a "file"
//  field — no Content-Type header, no "type" — see the Upload Asset section above.)
async function uploadAndWaitForAsset(url, type = "IMAGE") {
  const res = await fetch(`${BASE}/assets/upload`, {
    method: "POST",
    headers,
    body: JSON.stringify({ url, type }),
  });
  if (!res.ok) throw new Error(`Upload failed: ${(await res.json()).message}`);
  const asset = await res.json();
  console.log(`Asset uploaded: ${asset.assetId}, status: ${asset.status}`);

  // Poll until review completes
  while (true) {
    const statusRes = await fetch(
      `${BASE}/assets/status?assetId=${asset.assetId}`,
      { headers }
    );
    const status = await statusRes.json();
    if (status.status === "ACTIVE") {
      console.log(`Asset approved: asset://${status.volcAssetId}`);
      return status.volcAssetId;
    }
    if (status.status === "FAILED") {
      throw new Error(`Asset review failed: ${status.failReason}`);
    }
    await new Promise((r) => setTimeout(r, 3000));
  }
}

// 2. Create a task
async function createTask(inputs, callBackUrl) {
  const res = await fetch(`${BASE}/jobs/createTask`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      model: "sd2",
      inputs,
      ...(callBackUrl && { callBackUrl }),
    }),
  });
  if (!res.ok) throw new Error(`[${res.status}] ${(await res.json()).message}`);
  return res.json();
}

// 3. Poll until done
async function waitForResult(taskId, timeoutMs = 300000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const res = await fetch(
      `${BASE}/jobs/queryTask?taskId=${taskId}`,
      { headers }
    );
    const result = await res.json();
    if (result.status === "COMPLETED") return result;
    if (result.status === "FAILED") throw new Error(result.error);
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("Timeout waiting for task");
}

// Full workflow: upload → review → generate → result
async function main() {
  // Upload image and wait for review
  const volcAssetId = await uploadAndWaitForAsset(
    "https://example.com/photo.jpg", "IMAGE"
  );

  // Create task with approved asset
  const { taskId } = await createTask({
    urls: [`asset://${volcAssetId}`],
    prompt: "The person slowly looks up and smiles",
    duration: "5s",
  });
  console.log(`Task: ${taskId}`);

  // Wait for video
  const result = await waitForResult(taskId);
  console.log(`Video: ${result.output[0].url}`);
}

main().catch(console.error);

Need help? Join our Discord or contact us

SeeGen AI API

Overview

Why SeeGen AI?

More Reasons to Choose SeeGen AI:

Pricing

API Pack

API-XL Pack

Authentication

Quick Start

Endpoints

Choose a Model (Video)

Seedance 2.0 / 2.0 Fast / 2.0 Mini / Seedance 2.5

Text to Video

Image to Video

First & Last Frame

Multi-Reference

Video Edit & Extend

Seedance Parameters Reference

Assets

Upload Asset

Upload Response

Query Asset Status

List Assets

List Response

Using Assets in Tasks

HappyHorse 1.1 (Alibaba)

Text-to-Video

Image-to-Video (First Frame)

Reference-to-Video (1–9 Reference Images)

HappyHorse Parameters Reference

Choose a Model (Image)

GPT Image 2

Text-to-Image

Image-to-Image (Editing)

GPT Image 2 Parameters Reference

Nano Banana 2

Text-to-Image

Image-to-Image (Editing)

Nano Banana 2 Parameters Reference

Nano Banana Pro

Text-to-Image

Image-to-Image (Editing)

Nano Banana Pro Parameters Reference

Seedream 5.0 Lite

Text-to-Image

Image-to-Image (Editing)

Seedream 5.0 Lite Parameters

Seedream 5.0 Pro

Text-to-Image

Image-to-Image (Editing)

Seedream 5.0 Pro Parameters

Video Upscaler

Create Task

Create Response

Query Status

Completed Response

Failed Response

Error Codes

Webhook Callback

Callback Payload

Response Format

createTask Response

queryTask Response

credits Response

Error Handling

Pre-submit validation (400 with a code)

Full Examples