Text to Video API Tutorial: First AI Video Render in 5 Minutes

Text-to-Video API: Submit Your First Render in 5 Minutes

You can submit a first text-to-video job in about five minutes. The render itself may take longer: generation time depends on the model, duration, resolution and provider load.

The SamAutomation flow has three API calls:

1. GET /api/ai/models?type=video to discover the models that are active now.
2. POST /api/ai/jobs to submit a prompt and receive a job_id.
3. GET /api/ai/jobs/{id} to poll until the job succeeds or fails.

Use the X-API-Key header on every request. Do not hard-code a model price or model list: the catalog response is the current source for availability, options and credit cost.

Before you send a job

Create an account, open the dashboard and copy your SamAutomation API key. You can compare the current plans on the pricing page and inspect the complete request reference in the AI API documentation.

Keep the key in an environment variable or secret store. Never paste it into frontend JavaScript, a public repository or an n8n workflow export.

Step 1: list the live video models

Start with the catalog instead of guessing a model ID:

curl "https://samautomation.work/api/ai/models?type=video" \
  -H "X-API-Key: YOUR_SAMAUTOMATION_API_KEY"

Choose a model whose capabilities match the job. A text-to-video model accepts a prompt only. An image-to-video model also needs one or more image_urls. Read the returned options before setting duration, resolution or aspect ratio; supported values differ per model.

The examples below use wan-2-7-t2v, the model ID shown in the current API quickstart. If the catalog no longer returns that ID, use a live text-to-video ID from your own response.

Step 2: write a prompt that can fit in one clip

A useful first prompt contains five concrete parts:

[subject] + [action] + [setting] + [visual style] + [camera movement]

For example:

A ceramic coffee cup steaming on a walnut desk at sunrise,
warm window light, cinematic product shot, slow push-in.

Keep the scene narrow. One subject and one camera action are easier to judge than a prompt containing multiple locations, people and story beats. Generate readable titles and prices later in JSON-to-Video; generative footage is a poor place for exact on-screen text.

Step 3: submit the text-to-video job

curl -X POST "https://samautomation.work/api/ai/jobs" \
  -H "X-API-Key: YOUR_SAMAUTOMATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "wan-2-7-t2v",
    "prompt": "A ceramic coffee cup steaming on a walnut desk at sunrise, warm window light, cinematic product shot, slow push-in",
    "options": {
      "resolution": "1080p",
      "duration_s": 10,
      "aspect_ratio": "16:9"
    }
  }'

A valid submission returns HTTP 202 with a response shaped like this:

{
  "success": true,
  "job_id": 123,
  "status": "running",
  "credits_charged": 80,
  "credits_remaining": 920
}

The numbers are examples. Use the values returned by your request. If the account lacks enough credits, the API returns HTTP 402 without starting the job.

Step 4: poll until the render is ready

Use the returned job ID:

curl "https://samautomation.work/api/ai/jobs/123" \
  -H "X-API-Key: YOUR_SAMAUTOMATION_API_KEY"

Poll with a short delay rather than sending requests continuously. A finished job returns status: "success" and one or more URLs in result_urls. A failed job contains an error code and message; failed generation jobs are refunded automatically by the job service.

This small Python example submits and polls the same workflow:

import os
import time
import requests

base_url = "https://samautomation.work/api/ai"
headers = {
    "X-API-Key": os.environ["SAMAUTOMATION_API_KEY"],
    "Content-Type": "application/json",
}

job = requests.post(
    f"{base_url}/jobs",
    headers=headers,
    json={
        "model_id": "wan-2-7-t2v",
        "prompt": "A ceramic coffee cup on a desk at sunrise, slow push-in",
        "options": {"resolution": "1080p", "duration_s": 10, "aspect_ratio": "16:9"},
    },
    timeout=30,
)
job.raise_for_status()
job_id = job.json()["job_id"]

while True:
    status = requests.get(f"{base_url}/jobs/{job_id}", headers=headers, timeout=30)
    status.raise_for_status()
    data = status.json()

    if data["status"] == "success":
        print(data["result_urls"])
        break
    if data["status"] == "failed":
        raise RuntimeError(data.get("error_message") or "Video generation failed")

    time.sleep(5)

For a production integration, add a maximum polling time, retry only temporary network errors and store the job_id so a process restart does not submit the same paid job twice.

Turn the raw clip into a publishable video

The model output is usually one scene, not a finished campaign asset. A reliable production pipeline separates generation from composition:

1. Generate or animate the source clip.
2. Review faces, hands, logos, product details and unwanted artifacts.
3. Add exact text, a logo, music and transitions with JSON-to-Video.
4. Add timed subtitles with AutoCaptions when the video contains speech.
5. Export the correct aspect ratio for the destination platform.

This split matters. The generative model handles motion and imagery; the deterministic renderer handles brand elements that must be pixel-accurate.

When image-to-video is the better starting point

Use image-to-video when a product, person or visual style must start from a specific reference. List models with an image-to-video capability, then pass the reference URL:

{
  "model_id": "A_LIVE_IMAGE_TO_VIDEO_MODEL_ID",
  "prompt": "Slow push-in, subtle steam, keep the cup shape and logo unchanged",
  "image_urls": ["https://example.com/coffee-cup.jpg"],
  "options": {
    "duration_s": 5,
    "resolution": "720p"
  }
}

The reference improves control, but it does not guarantee an unchanged product or logo. Review the output before publishing.

Common errors

401 or a missing API key error

Send the key as X-API-Key. The AI endpoints do not use the Authorization: Bearer header shown in many unrelated APIs.

404 Model not found

The model ID is inactive or misspelled. Fetch GET /api/ai/models?type=video again and use the returned public ID.

402 Insufficient credits

Check GET /api/ai/credits/balance, lower the requested settings if the chosen model supports that, or add credits through the account.

403 Model not allowed for your plan

The model exists but is not included in the current account tier. Choose an allowed catalog entry or compare the plans.

The video contains distorted text or product details

Remove exact text from the generative prompt and add it during composition. For products, use a reference image and reject renders that alter brand-critical details.

The live AI API documentation remains the canonical reference for endpoints, request options and response fields.

Questions people ask

How does a text-to-video API work?

Three calls. You POST a payload describing the video, you get a job id back, and you poll that id until the status is done and an output URL appears. Everything else — models, queues, storage — sits behind those three calls.

What is an API, in plain terms?

An address your program can call instead of a person clicking. You send a request in an agreed shape, you get an answer in an agreed shape.

Do I need to wait for the render?

No, and you should not block on it. Poll on an interval or take a webhook callback. Blocking a request thread on a two-minute render is the first thing that falls over under load.

Is text-to-speech included?

Narration is a separate step: the voice is generated from your script, then the audio drives the video timing. Bundling them in one request is convenient, but they are still two jobs underneath.

Is a text-to-speech API free?

Free tiers exist, usually capped by characters per month and with a limited voice list. If the same voice has to appear in every video for a year, budget for a paid one — free voice line-ups change.