API reference · GotoRamp Video docs

Early-access reference: the endpoint opens with your account invitation; field names and error codes are frozen at launch.

Base URL and auth

All requests go to https://api.gotoramp.ai/v1 and carry your key as a bearer token:

Authorization: Bearer $GOTORAMP_API_KEY

Keys are scoped to one account. Each key has its own usage, spend limit and optional model allowlist. Requests from countries we don't serve are refused regardless of the key.

Create a job

POST /v1/video/generations creates an asynchronous job and returns immediately.

Field	Type	Required	Description
`model`	string	Yes	`seedance-2.5`, `seedance-2.0`, `seedance-2.0-fast` or `seedance-2.0-mini`
`prompt`	string	Yes	What happens in the shot: subject, action, camera, light, sound.
`duration`	integer	No	Seconds, 4–15. Default 5.
`image`	string	No	First frame, as an HTTPS URL or base64 data URI.
`seed`	integer	No	Repeat a result more closely with the same inputs.
`metadata`	object	No	Format, audio and reference options. See Request options.
`user`	string	No	Your end-user ID. Platforms should always set it so abuse reports can be traced.

{
  "model": "seedance-2.0",
  "prompt": "The rattan lounge chair turns slowly on a white sweep, soft studio shadow",
  "duration": 8,
  "image": "https://example.com/packshots/rattan-chair.jpg",
  "metadata": {
    "ratio": "1:1",
    "resolution": "720p",
    "generate_audio": true
  },
  "user": "workspace-2291"
}

{
  "id": "vid_01J9Q7Z4M2",
  "object": "video",
  "model": "seedance-2.0",
  "created_at": 1790000000,
  "task_id": "vid_01J9Q7Z4M2",
  "status": "queued"
}

Request options

Set inside metadata.

Field	Type	Description
`ratio`	string	`21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `adaptive` to follow the first frame. Default `16:9`.
`resolution`	string	`480p` or `720p`. Default `720p`.
`generate_audio`	boolean	Generate sound with the picture. Default `true`.
`last_frame_image`	string	Where the shot should end. Requires `image`.
`reference_images`	string[]	Images that steer identity, product or set.
`reference_videos`	string[]	Short clips that steer motion and camera language.
`reference_audios`	string[]	Audio that steers rhythm and timing.

Get a job

GET /v1/video/generations/{task_id} returns the job's current state. When it has succeeded, url points to the MP4 and metadata describes it.

Response · 200

{
  "task_id": "vid_01J9Q7Z4M2",
  "status": "succeeded",
  "format": "mp4",
  "url": "https://api.gotoramp.ai/files/vid_01J9Q7Z4M2.mp4",
  "metadata": { "duration": 8, "fps": 24, "width": 720, "height": 720, "seed": 48213 },
  "error": null
}

Job statuses

Status	Meaning	What to do
`queued`	Accepted, waiting for capacity	Keep polling
`in_progress`	Generating	Keep polling
`succeeded`	Video ready at `url`	Download within 24 hours
`failed`	Stopped; see `error`	Fix the input or retry. Not billed.

Limits

Limit	Value
Duration	4–15 seconds, whole seconds
Resolution	480p, 720p
Aspect ratios	21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive
References per job	Up to 9 images, 3 video clips and 3 audio clips on `seedance-2.0`; lower on some models
Video link lifetime	24 hours from success

The console lists the exact limits for each model. A request outside a model's limits fails at submission with 400 and isn't billed.

Errors

Errors return a JSON body with a machine-readable code and a human-readable message.

Error · 403

{
  "error": {
    "code": "region_not_available",
    "message": "GotoRamp Video isn't offered in the country this request came from."
  }
}

HTTP	code	Cause and fix
400	`invalid_request`	A field is missing or outside the model's limits. The message names the field.
401	`invalid_api_key`	Key missing, revoked or mistyped.
402	`insufficient_balance`	Top up, or raise the key's spend limit.
403	`region_not_available`	The request came from a country we don't serve.
403	`content_policy`	The prompt or a reference breaks the content rules. Not billed.
404	`task_not_found`	Unknown task ID, or a task from another account.
429	`rate_limited`	Too many jobs running at once. Retry with backoff.
5xx	`upstream_error`	Temporary model-side failure. Retry with backoff; not billed.

Rate limits and concurrency

Each account has a limit on jobs running at the same time. Pay as you go accounts get standard concurrency; Volume and Enterprise accounts get more, agreed in writing. When you hit the limit you get 429: back off and retry, or queue jobs on your side.

Versioning and changes

The /v1 path is stable. We add fields without notice, but we announce removals, renames and model-version changes at least 30 days ahead by email to account owners.