Quickstart · GotoRamp Video docs

Early access. API keys and the endpoint api.gotoramp.ai open with your account invitation. Request early access to get yours.

Before you start

An approved GotoRamp account in one of our available countries.
A positive balance. Mini at 480p is the lowest-cost way to test.
curl, Python 3.9+ with requests, or Node.js 18+ (built-in fetch).

1. Create a key

In the console, open API keys, create a key for this project and set a spend limit. Copy the key once; it isn't shown again. Store it in an environment variable, never in source code.

export GOTORAMP_API_KEY="paste-your-key-here"

$env:GOTORAMP_API_KEY = "paste-your-key-here"

2. Submit a job

Send the model, a prompt and a duration. Everything else has a sensible default: 720p, 16:9, audio on.

curl https://api.gotoramp.ai/v1/video/generations \
  -H "Authorization: Bearer $GOTORAMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini",
    "prompt": "Longtail boat on a Bangkok canal at sunrise, low angle from the water line",
    "duration": 5,
    "metadata": { "resolution": "480p" }
  }'

import os, requests

API = "https://api.gotoramp.ai/v1"
H = {"Authorization": f"Bearer {os.environ['GOTORAMP_API_KEY']}"}

job = requests.post(f"{API}/video/generations", headers=H, json={
    "model": "seedance-2.0-mini",
    "prompt": "Longtail boat on a Bangkok canal at sunrise, low angle from the water line",
    "duration": 5,
    "metadata": {"resolution": "480p"},
}, timeout=60)
job.raise_for_status()
task_id = job.json()["task_id"]

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

const res = await fetch(`${API}/video/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "seedance-2.0-mini",
    prompt: "Longtail boat on a Bangkok canal at sunrise, low angle from the water line",
    duration: 5,
    metadata: { resolution: "480p" },
  }),
});
const { task_id } = await res.json();

The response contains a task_id and a status of queued. Keep the task ID; it's the only handle on the job.

3. Poll the job

Jobs usually take tens of seconds to a few minutes, depending on model, length and load. Poll every 5 seconds for the first 30 seconds, every 10 seconds up to 2 minutes, then every 30 seconds, and give up after 10 minutes.

curl https://api.gotoramp.ai/v1/video/generations/TASK_ID \
  -H "Authorization: Bearer $GOTORAMP_API_KEY"

import time

def wait_for(task_id, timeout=600):
    start = time.time()
    while time.time() - start < timeout:
        task = requests.get(f"{API}/video/generations/{task_id}", headers=H, timeout=30).json()
        if task["status"] in ("succeeded", "failed"):
            return task
        waited = time.time() - start
        time.sleep(5 if waited < 30 else 10 if waited < 120 else 30)
    raise TimeoutError(task_id)

task = wait_for(task_id)
print(task["status"], task.get("url"))

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function waitFor(taskId, timeoutMs = 600_000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const task = await fetch(`${API}/video/generations/${taskId}`, { headers }).then((r) => r.json());
    if (task.status === "succeeded" || task.status === "failed") return task;
    const waited = Date.now() - start;
    await sleep(waited < 30_000 ? 5_000 : waited < 120_000 ? 10_000 : 30_000);
  }
  throw new Error(`timed out: ${taskId}`);
}

const task = await waitFor(task_id);
console.log(task.status, task.url);

4. Download the video

When the status is succeeded, the task has a url to an MP4.

Download within 24 hours. Video links expire and we don't keep a copy. Copy the file to your own storage as soon as the job succeeds.

Next steps

Add reference images, video or audio: request options.
Handle errors and rate limits: error codes.
Choose the right model for each stage: model comparison.
Read the rules before you publish: Acceptable Use Policy.