viduq3

Quick example

curl https://reapi.ai/api/v1/videos/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-pro",
    "prompt": "A kitten playing piano, slow camera push-in",
    "duration": 8,
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }'

import requests

resp = requests.post(
    "https://reapi.ai/api/v1/videos/generations",
    headers={
        "Authorization": "Bearer rk_live_xxx",
        "Content-Type": "application/json",
    },
    json={
        "model": "viduq3-pro",
        "prompt": "A kitten playing piano, slow camera push-in",
        "duration": 8,
        "resolution": "1080p",
        "aspect_ratio": "16:9",
    },
    timeout=30,
)
print(resp.json())

const r = await fetch("https://reapi.ai/api/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer rk_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "viduq3-pro",
    prompt: "A kitten playing piano, slow camera push-in",
    duration: 8,
    resolution: "1080p",
    aspect_ratio: "16:9",
  }),
});
console.log(await r.json());

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "model":        "viduq3-pro",
        "prompt":       "A kitten playing piano, slow camera push-in",
        "duration":     8,
        "resolution":   "1080p",
        "aspect_ratio": "16:9",
    })
    req, _ := http.NewRequest("POST",
        "https://reapi.ai/api/v1/videos/generations", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer rk_live_xxx")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    out, _ := io.ReadAll(resp.Body)
    fmt.Println(string(out))
}

Submit response

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "viduq3-pro",
  "status": "processing",
  "created_at": 1735000000
}

Poll GET /api/v1/tasks/{id} (see the Tasks reference) until status === "completed". The completed payload's output.video_urls holds the generated MP4 URL, valid for 7 days.

Authentication

Every call needs a Bearer token. Generate keys at reapi.ai/settings/apikeys.

Authorization: Bearer YOUR_API_KEY

Keys carry the active workspace's billing scope — there is no separate project header.

Endpoint

POST /api/v1/videos/generations
GET  /api/v1/tasks/{id}

Submission is async. The POST returns immediately with a task_id; the task endpoint returns the same envelope until completion. Polling does not consume credits.

Variants

Both variants share one parameter shape; pick via model:

reAPI never silently substitutes one variant for another — what you send in model is what gets billed and forwarded.

Mode routing

viduq3 picks its mode from the count of image_urls you send — there is no mode parameter:

Request body

model — required

string. One of "viduq3-pro" or "viduq3-turbo".

prompt — string, conditional

Up to 2,000 characters. Required in T2V (when image_urls is empty); optional in I2V and First/Last when at least one image is provided.

Empty / whitespace-only prompts are treated as missing.

duration — integer, default 5

Output length in seconds. Any integer in [1, 16]. Out-of-range → 400. Drives pricing linearly: ceil(per_second_usd × duration × 1000) credits (1 credit = $0.001).

resolution — string, default "720p"

540p / 720p / 1080p. Drives pricing. Lowercase is canonical; uppercase forms ("1080P") are accepted and normalized.

aspect_ratio — string, T2V only

Output ratio in T2V mode. One of:

image_urls — string[]

Array of public HTTP(S) URLs. 0 to 2 entries:

• 0 entries — pure text-to-video.
• 1 entry — image-to-video; the image is treated as the first frame.
• 2 entries — first/last-frame transition. The first URL is the starting frame; the second URL is the ending frame.

audio — boolean, default true

When true, the model synthesizes an audio track (dialogue, sound effects) that plays alongside the generated video. Set to false for silent output. Audio generation does not change the per-second rate.

seed — integer

Reproducibility hint. Range [-1, 4294967295]. Same seed plus an otherwise identical request returns a similar (not bit-for-bit identical) result. Use -1 (or omit) for full randomness.

Response envelope

Submit and poll share the same shape — only status and output fill in over time.

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "viduq3-pro",
  "status": "completed",
  "created_at": 1735000000,
  "output": {
    "video_urls": ["https://cdn.reapi.ai/media/tasks/018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e/0.mp4"]
  },
  "error": null
}

output.video_urls URLs are valid for 7 days. Re-host to your own storage if you need them longer.

Validation errors

All cases below return HTTP 400 with code 20003 unless noted. Pattern-match on code, not message — message strings carry request-specific context (field names, observed values, etc.) and are not a stable contract.

The full envelope is { "error": { "code", "message", "request_id" } } — see Errors catalog for the wire format and request_id correlation tips.

Recipes

T2V — minimum request

{
  "model": "viduq3-pro",
  "prompt": "A little girl walking down a sunset coastal road"
}

T2V — full parameters

{
  "model": "viduq3-pro",
  "prompt": "A kitten playing piano, slow camera push-in, cinematic warm tones",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "audio": true,
  "seed": 42
}

I2V — animate a single frame

{
  "model": "viduq3-pro",
  "prompt": "Bring the scene to life with a gentle camera dolly forward",
  "image_urls": ["https://your-cdn.com/first_frame.jpg"],
  "duration": 5,
  "resolution": "1080p"
}

First/Last-frame transition

{
  "model": "viduq3-pro",
  "prompt": "Smooth motion from standing to seated",
  "image_urls": [
    "https://your-cdn.com/standing.jpg",
    "https://your-cdn.com/seated.jpg"
  ],
  "duration": 8
}

Silent video — disable audio

{
  "model": "viduq3-pro",
  "prompt": "Sunset timelapse over the ocean",
  "duration": 10,
  "resolution": "1080p",
  "audio": false
}

Turbo — cost-conscious

{
  "model": "viduq3-turbo",
  "prompt": "Waves crashing on a beach at sunset, wide shot",
  "duration": 5,
  "resolution": "720p"
}

Choosing a mode

Polling pattern

The task endpoint behaves identically to other video tasks — the only difference is the completed output shape (video_urls instead of image_urls). A pragmatic schedule:

0–5 minutes:    poll every 5s
5 min – 1 h:    back off gradually toward 1 min
≥ 1 h:          cap at 3 min between polls

A typical task completes in a few minutes. The worker's wall-clock cap is 48 hours, comfortably above any realistic queue.

Pricing

Per-second × resolution. Mode does not change the rate. Turbo undercuts Pro at every tier. See current rates on the Vidu Q3 model page.

Bill formula (1 credit = $0.001):

credits = ceil(per_second_usd × duration × 1000)

Failed jobs refund automatically.

Tips

• Prompt motion, not just scene. "Slow push-in, warm tones, shallow depth of field" outperforms a pure noun-list of what's on screen.
• Sweet-spot duration: 5–10 seconds. Below 5s motion looks choppy; above 10s the upstream wall-time grows fast.
• First-frame quality matters. Subject centered, clear composition, no heavy filters — I2V output quality tracks input quality directly.
• Two frames need to make sense as endpoints. First/Last works best when the two frames share enough subject and composition that the model can interpolate motion between them — wildly different shots produce abrupt transitions.
• Pick Turbo first if you're iterating. It's roughly half the cost per second; lock the prompt on Turbo, then re-render the keeper on Pro at the resolution you'll ship.

Related

• Errors catalog
• Authentication
• Quickstart