Create Generation

Submit a prompt (and optional image) to generate a video or image.

POST /api/v1/generations

Create Generation

cURL

curl --request POST \
  --url https://veogen.studio/api/v1/generations \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "prompt": "<string>",
  "aspect_ratio": "<string>",
  "resolution": "<string>",
  "duration": 123,
  "mode": "<string>",
  "style": "<string>",
  "image_urls": [
    {}
  ],
  "video_urls": [
    {}
  ],
  "audio_urls": [
    {}
  ],
  "watermark": true,
  "private": true
}
'

200

{
  "data": {
    "id": "<string>",
    "status": "<string>",
    "model": "<string>",
    "type": "<string>",
    "prompt": "<string>",
    "parameters": {},
    "output": {},
    "error": {},
    "created_at": "<string>",
    "completed_at": {}
  },
  "price_usd": 123
}

Request

Authorization · string · required

Bearer YOUR_TOKEN

model · string · required

The model slug to use. See Models for all available slugs.

Video models: grok-video-1, veo-3.1-fast, sora-2, sora-2-pro, seedance-2.0, seedance-2.0-fast

Image models: gpt-4o-image, seedream-4.5, seedream-5.0-lite, nano-banana-pro, nano-banana-2

prompt · string · required

The text prompt describing what to generate. Maximum 2,000 characters.

aspect_ratio · string

The output aspect ratio. Defaults to the model’s first supported ratio.

Common values: 16:9, 9:16, 1:1, 4:3

resolution · string

Output resolution. Only applicable to models that support multiple resolutions.

Video: 480p, 720p, 1080p, 4k (model-dependent)

Image: 0.5K, 1K, 2K, 4K (model-dependent)

Resolution multipliers increase the price. A 4k video on Veo 3.1 Fast costs 3× the base price. Seedance 2.0 720p costs ~2.15× the 480p rate. See Pricing.

duration · integer

Duration in seconds. Only for video models. Accepted values depend on the model:

• grok-video-1: 6–30 seconds (billed per second at $0.03/s)
• sora-2: 10 or 15 seconds
• sora-2-pro: 10, 15, or 25 seconds
• seedance-2.0: 4–15 seconds (billed per second at $0.132/s for 480p,$0.284/s for 720p)
• seedance-2.0-fast: 4–15 seconds (billed per second at $0.1056/s for 480p,$0.2288/s for 720p)

Seedance models have reduced pricing when a reference video is provided via video_urls. See the video_urls parameter below.

mode · string

Generation mode. Model-specific:

• grok-video-1: custom, normal, fun, spicy
• veo-3.1-fast: frame (image-to-video), ingredient (reference images)

style · string

Visual style preset. Only for sora-2 and sora-2-pro.

Values: none, thanksgiving, comic, news, selfie, nostalgic, anime

image_urls · array

Array of publicly accessible image URLs to use as input. Maximum count is model-dependent (up to 14 for image models).

For video models, the first URL is used as the first frame. Additional images are treated as reference images.

video_urls · array

Array of publicly accessible video URLs to use as reference input. Up to 3 URLs. Seedance 2.0 / 2.0 Fast only.

When provided, the generation uses the reference video to guide output, and the price is discounted:

Model	480p	720p
seedance-2.0	$0.08/s (vs$0.132/s)	$0.1712/s (vs$0.284/s)
seedance-2.0-fast	$0.0632/s (vs$0.1056/s)	$0.136/s (vs$0.2288/s)

Supported formats: MP4, WebM, MOV.

audio_urls · array

Array of publicly accessible audio URLs to use as reference input. Up to 3 URLs. Seedance 2.0 / 2.0 Fast only.

Supported formats: MP3, WAV, M4A, OGG.

watermark · boolean

Whether to add a watermark to the output. Defaults to false. Only for sora-2 and sora-2-pro.

private · boolean

Whether the generation should be private. Only for sora-2 and sora-2-pro.

---

Response 201 Created

data · object

Show Generation object

id · string

UUID of the generation. Use this to poll for status.

status · string

pending | processing | completed | failed

model · string

The model slug used.

type · string

video | image

prompt · string

The prompt submitted.

parameters · object

Resolved parameters (aspect_ratio, duration, resolution, mode).

output · object | null

null until status is completed. Then contains url and content_type.

error · string | null

Error message. Only present when status is failed.

created_at · string

ISO 8601 timestamp.

completed_at · string | null

ISO 8601 timestamp when generation finished.

price_usd · number

The exact USD amount charged for this generation.

---

Error Responses

402 Insufficient Balance

{
  "error": "Insufficient balance.",
  "message": "This generation costs $0.30. Your balance is $0.05.",
  "required": 0.30,
  "balance": 0.05
}

Top up at veogen.studio/billing.

422 Validation Error

{
  "message": "The model field is required.",
  "errors": {
    "model": ["The model field is required."]
  }
}

---

Examples

Image — GPT-4o

curl -X POST https://veogen.studio/api/v1/generations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-image",
    "prompt": "A serene mountain landscape at sunset, photorealistic",
    "aspect_ratio": "16:9"
  }'