FreeRap Template API

Generate a template video from a reference image. Create a task, then query its status to retrieve the finished video.

Base URLhttps://freerapvideo.com

Get started

Make your first request in four steps. Run these commands from your terminal or backend.

1
Create an API key
Open Settings → API, create a key, and store the full sk_ secret in an environment variable. Keep it on your server.
Create an API key
Shell
```
export FREERAP_API_KEY='YOUR_API_KEY'
```
2
Choose a template and settings
Fetch the public template catalog. Choose a slug and a model/resolution pair listed in its rows. Check name, imageSlots, and defaultDurationSec. No API key is required for this catalog.
GET /api/template-prices
```
curl https://freerapvideo.com/api/template-prices
```

Create a video task

This example uses bulin with one reference image and pro / 720p. Confirm that combination is priced, replace the example image with your public HTTPS image, then save data.taskId from the response.

POST · cURL

curl --request POST \
  'https://freerapvideo.com/api/v1/templates/bulin/generations' \
  --header "Authorization: Bearer $FREERAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "reference_image_urls": ["https://cdn.example.com/face.jpg"],
    "model": "pro",
    "resolution": "720p"
  }'

4
Get the result
Replace TASK_ID with data.taskId. Query about every 30 seconds until success, failed, or canceled. On success, read data.videos.
GET · cURL
```
curl 'https://freerapvideo.com/api/v1/generations/TASK_ID' \
  --header "Authorization: Bearer $FREERAP_API_KEY"
```

Authentication

Send the Authorization header on both task endpoints. Use the full sk_ key from Settings → API. A missing or invalid key returns HTTP 401. Never expose the key in browser code.

HTTP

Authorization: Bearer <API_KEY>

API reference

The template supplies the prompt, reference video, and soundtrack. Clients supply the reference image and generation settings. Callback URLs are not supported; query the task for results.

Successful calls use HTTP 200 with code 0, message ok, and a data object. Request errors use code -1 and message. A successful query can report a failed generation in data.status.

Create a task

POST/api/v1/templates/{campaign}/generations

Starts an asynchronous video generation for an active template. HTTP 200 confirms task creation; the video is still processing.

Required headers: Authorization: Bearer <API_KEY> and Content-Type: application/json.

Path parameters

Create a task: Path parameters
Field	Type	Required	Description
`campaign`	string	Yes	Active template slug, for example bulin. Look it up in GET /api/template-prices.

Request body

New integrations use reference_image_urls, model, and resolution. These are the common fields for every template.

Create a task: Request body
Field	Type	Required	Description
`reference_image_urls`	string[]	Yes	Exactly N non-empty public HTTPS image URLs, matching the template imageSlots. Array item 1 maps to @Image1, item 2 to @Image2, and so on. Order is preserved; every entry is required.
`model`	string	No	basic \| pro \| ultra. Default: pro. Must be priced for this template and resolution.
`resolution`	string	No	480p \| 720p \| 1080p. Default: 720p. basic allows 480p and 720p. pro and ultra also allow 1080p. Must be priced for the selected model.

Reference image requirements

reference_image_urls must contain exactly N publicly accessible HTTPS image URLs, where N is the template imageSlots value returned by GET /api/template-prices (1–5). Each URL must serve JPEG, PNG, or WebP, up to 10 MB by default, on port 443. Empty strings, null entries, missing entries, and extra entries return HTTP 400. The server retrieves and stores each image before generation. Local files, private network addresses, and URLs requiring authentication are not supported.

Template settings

Models: basic supports 480p and 720p. pro and ultra also support 1080p. Only priced combinations for the chosen template are available. GET /api/template-prices lists current combinations and template metadata. Duration and aspect ratio are template-controlled: omit duration and aspect_ratio. image_url, effect, slots, prompt, reference_video_urls, callBackUrl, and unknown fields are rejected with HTTP 400.

Aspect ratio is configured by the template: 9:16, 16:9, or adaptive. Adaptive follows the template reference video. Do not send aspect_ratio (HTTP 400). The stored prompt, reference media, duration, and image count define one fixed effect for every model.

GET /api/template-prices

Success response

Example values only. The 30-credit amount is illustrative; use the quote returned by your request.

HTTP 200 · JSON

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "credits_estimate": 30,
    "credits_charged": 30
  }
}

Create a task: Response fields
Field	Type	Required	Description
`data.taskId`	string (uuid)	Yes	Task UUID returned by the create endpoint.
`data.status`	string	Yes	Always processing when creation succeeds.
`data.credits_estimate`	integer	Yes	Quoted task price in credits, reserved at creation.
`data.credits_charged`	integer	Yes	Reserved credits while running; final retained charge at a terminal state, after any refund.

Multiple reference images

For a template configured with imageSlots = 3, send exactly three URLs in prompt reference order. Replace YOUR_TEMPLATE_SLUG with that template’s slug. This example does not imply that Bulin or Dame Hombro requires three images. There are no position, effect, or slots parameters.

POST · cURL

curl --request POST \
  'https://freerapvideo.com/api/v1/templates/YOUR_TEMPLATE_SLUG/generations' \
  --header "Authorization: Bearer $FREERAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "reference_image_urls": ["https://cdn.example.com/image-1.jpg", "https://cdn.example.com/image-2.jpg", "https://cdn.example.com/image-3.jpg"],
    "model": "pro",
    "resolution": "720p"
  }'

Errors · HTTP 400 / 401 / 402 / 403 / 404 / 429 / 500 / 503

Query a task

GET/api/v1/generations/{taskId}

Returns the current status of an API-created task belonging to the API key’s user. No request body. Use the same key as creation, or another valid key belonging to the same user.

Query a task: Path parameters
Field	Type	Required	Description
`taskId`	string (uuid)	Yes	Task UUID returned by the create endpoint.

Success response

HTTP 200 · JSON

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "campaign": "bulin",
    "costCredits": 30,
    "credits_estimate": 30,
    "credits_charged": 30,
    "createdAt": "2026-10-31T00:00:00.000Z",
    "videos": [
      "https://media.example.com/generated/video.mp4"
    ]
  }
}

Query a task: Response fields
Field	Type	Required	Description
`data.taskId`	string (uuid)	Yes	Task UUID returned by the create endpoint.
`data.status`	string	Yes	pending \| processing \| success \| failed \| canceled. See task states below.
`data.campaign`	string	No	Public template slug. May be absent on historical tasks.
`data.credits_estimate`	integer	Yes	Quoted task price in credits, reserved at creation.
`data.credits_charged`	integer	Yes	Reserved credits while running; final retained charge at a terminal state, after any refund.
`data.costCredits`	integer	Yes	Compatibility field with the same value as credits_charged.
`data.createdAt`	string (date-time)	Yes	Creation time in ISO 8601 format (UTC).
`data.videos`	string[]	Yes	Video URLs hosted on FreeRap storage when successful; an empty array for other states.
`data.error`	string	No	Error description when available. Absent during pending or processing; not a stable error code.

Task states

Task states
Status	Terminal	Description
`pending`	No	Queued. Continue querying.
`processing`	No	Generating. Continue querying.
`success`	Yes	Complete. Read videos and stop querying.
`failed`	Yes	Failed. Read error when present and stop querying.
`canceled`	Yes	Canceled. Stop querying.

Query about every 30 seconds. Stop at a terminal state. A query timeout does not mean the generation failed; query the same task again.

Generation failure

HTTP 200 and code 0 mean the query succeeded. The generation itself may have failed: always inspect data.status. A failed task has an empty videos array and may include error.

HTTP 200 · JSON

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "campaign": "bulin",
    "costCredits": 0,
    "credits_estimate": 30,
    "credits_charged": 0,
    "createdAt": "2026-10-31T00:00:00.000Z",
    "videos": [],
    "error": "Video generation failed."
  }
}

Errors · HTTP 401 / 404 / 429 / 500

Errors

Request errors use a non-2xx HTTP status and the body below. code is always -1 for these errors; distinguish error categories by HTTP status. message is explanatory text, not a stable machine-readable error identifier.

HTTP 402 · JSON

{
  "code": -1,
  "message": "Insufficient credits."
}

Errors
HTTP status	Endpoint	Cause	Action
`400`	POST	Invalid JSON, fields, image, model, resolution, or duration.	Correct the request before retrying.
`401`	POST / GET	Missing or invalid API key.	Check the Authorization header and key.
`402`	POST	Insufficient FreeRap balance. No task is started.	Add credits, then create the task.
`403`	POST	Template has no price for this model/resolution.	Choose a priced combination from /api/template-prices.
`404`	POST / GET	Template is unavailable, or task is missing, deleted, inaccessible, or not API-created.	Check the slug or task ID and account. Stop querying an unavailable task.
`429`	POST / GET	Request rate or 30-task in-flight limit exceeded.	Honor Retry-After if present, or wait for running tasks to finish.
`500`	POST / GET	Unexpected server error.	Retry queries later. A create may already have started; avoid duplicate submissions.
`503`	POST	Credit pricing, storage, or generation service is unavailable.	Retry later; contact support if it persists.

Credits & limits

Credits are reserved when the task is created. While pending or processing, credits_charged equals credits_estimate. Success keeps the charge. Failure or cancellation releases the reserve, minus any configured failure fee (default 0). Read credits_charged in the terminal response for the final amount.

Each API key allows up to 30 pending or processing tasks. Per server instance, create requests are limited to one per second and queries to five per second per key. HTTP 429 may include Retry-After in seconds; when absent, wait before retrying.

Create requests do not support an idempotency key. If a POST times out or returns a server error, it may already have created a task. Avoid blindly resubmitting it, as this can create duplicate tasks and charges.

Get started

Create an API key

Choose a template and settings

Create a video task

Get the result

Authentication

API reference

Create a task

Path parameters

Request body

Reference image requirements

Template settings

Success response

Query a task

Success response

Task states

Errors

Credits & limits