API Documentation

Authentication

Pass your key in the Authorization header of every request: Authorization: Bearer txtovid_sk_…. Keys are shown once at creation and stored hashed. Keys can be restricted to specific models and to specific request domains (matched against the Origin/Referer header). Never expose a key in client-side code — call the API from your backend.

Pricing

Identical to the web generator and always charged against your account balance. List price per engine: HappyHorse 1.1 — 720P $0.14/second · 1080P $0.18/second; Wan 2.7 — 720P $0.10/second · 1080P $0.15/second. A flat $0.05/second platform fee is added on top — e.g. a 5-second 720P HappyHorse video costs $0.95, the same video with Wan 2.7 costs $0.75. API generations are private (no public-share discount). Failed or moderation-blocked generations are refunded automatically; the effective charge applies only to successful videos.

Choosing an engine

Every create-generation request accepts an optional engine field: "happyhorse" (default) or "wan" (Wan 2.7). Wan 2.7 supports longer prompts (up to 5,000 characters) and an optional negative_prompt (up to 500 characters) describing what should NOT appear in the video. All other parameters are identical across engines.

Create a generation

POST https://txtovid.com/api/v1/generations — returns 202 with the generation id. Video generation takes 1–5 minutes; poll the status endpoint (below) every 10–15 seconds.

Text to Video — model: "t2v" (happyhorse-1.1-t2v · wan2.7-t2v)

curl -X POST https://txtovid.com/api/v1/generations \
  -H "Authorization: Bearer $TXTOVID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "t2v",
  "prompt": "A golden retriever surfing a turquoise wave at sunset, cinematic slow motion",
  "resolution": "720P",
  "ratio": "16:9",
  "duration_sec": 5
}'

Same request with the Wan 2.7 engine and a negative prompt:

curl -X POST https://txtovid.com/api/v1/generations \
  -H "Authorization: Bearer $TXTOVID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "t2v",
  "engine": "wan",
  "prompt": "A golden retriever surfing a turquoise wave at sunset, cinematic slow motion",
  "negative_prompt": "low resolution, worst quality, deformed",
  "resolution": "720P",
  "ratio": "16:9",
  "duration_sec": 5
}'

Image to Video — model: "i2v" (happyhorse-1.1-i2v · wan2.7-i2v)

No ratioparameter — per the model docs the output follows the input image's aspect ratio.

curl -X POST https://txtovid.com/api/v1/generations \
  -H "Authorization: Bearer $TXTOVID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "i2v",
  "prompt": "Slow push-in, steam rising from the cup, warm morning light shifting",
  "image_url": "https://example.com/product-shot.jpg",
  "resolution": "720P",
  "duration_sec": 5
}'

References to Video — model: "r2v" (happyhorse-1.1-r2v · wan2.7-r2v)

curl -X POST https://txtovid.com/api/v1/generations \
  -H "Authorization: Bearer $TXTOVID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "r2v",
  "prompt": "The character from [Image 1] walks through a neon-lit alley at night, rain reflections, cinematic tracking shot",
  "reference_image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "resolution": "720P",
  "ratio": "9:16",
  "duration_sec": 5
}'

Video Editing — model: "ve" (happyhorse-1.0-video-edit · wan2.7-videoedit)

No ratio— the output keeps the input video's aspect ratio and duration per the model docs.

curl -X POST https://txtovid.com/api/v1/generations \
  -H "Authorization: Bearer $TXTOVID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ve",
  "prompt": "Turn the entire video into a watercolor animation, keep the camera motion unchanged",
  "video_url": "https://example.com/clip.mp4",
  "reference_image_urls": [],
  "resolution": "720P",
  "duration_sec": 5
}'

Success response (202)

{
  "data": {
    "id": "cmrk4gpbf0005lj04…",
    "status": "SUBMITTED",
    "model": "t2v",
    "cost": "$0.95",
    "cost_cents": 95,
    "created_at": "2026-07-17T10:30:00.000Z",
    "poll_url": "https://txtovid.com/api/v1/generations/cmrk4gpbf0005lj04…"
  }
}

Poll status & get the video

GET https://txtovid.com/api/v1/generations/{id} — poll every 10–15 seconds until status is SUCCEEDED (video URLs included) or a failure state (error object included, charge refunded). Download the video promptly and store it on your side.

curl https://txtovid.com/api/v1/generations/GENERATION_ID \
  -H "Authorization: Bearer $TXTOVID_API_KEY"

Success response (200)

{
  "data": {
    "id": "cmrk4gpbf0005lj04…",
    "status": "SUCCEEDED",
    "cost": "$0.95",
    "cost_cents": 95,
    "duration_sec": 5,
    "resolution": "720P",
    "generation_time_sec": 84,
    "created_at": "2026-07-17T10:30:00.000Z",
    "completed_at": "2026-07-17T10:31:24.000Z",
    "error": null,
    "video": {
      "id": "vid_…",
      "url": "https://media.txtovid.com/videos/…/original.mp4",
      "thumbnail_url": "https://media.txtovid.com/videos/…/thumb.jpg",
      "width": 1280,
      "height": 720
    }
  }
}

Errors

Every error is JSON with a stable machine-readable code: { "error": { "code", "message" } }. Provider errors from Model Studio are translated into clear messages and correct HTTP codes.

Limits & best practices

• 20 generation requests per hour and 120 status polls per minute, per API key.
• All media URLs must be publicly reachable over HTTPS — the video model downloads them directly.
• Poll every 10–15 seconds; generations typically finish in 1–5 minutes.
• Result URLs are permanent on our CDN, but download and store important videos on your side.
• Rotate keys regularly and scope them: restrict models and domains per integration.
• Handle provider_busy and rate_limited with exponential backoff.