HTTP API documentation

Integrate Parafraim video creation into your product.

Use a server-side API key to create projects, send conversational edits, reuse templates, render MP4s, and inspect usage.

View endpoints Create API key

Base request

curl https://parafraim.com/api/v1/me \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY"

Base URL

https://parafraim.com

Quickstart

Make your first authenticated request

API keys are created from Settings -> API keys. The secret starts with pfk_, is shown once, and usage is billed to the owning account.

export PARAFRAIM_API_KEY="pfk_..."

curl https://parafraim.com/api/v1/me \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY"

Authentication

Use Bearer tokens and JSON bodies

Stable response envelope

Every JSON response uses a success flag. Lists add a pagination object.

Server-side keys

Use API keys from trusted backend code for production workflows. Do not embed keys in public apps.

Use API keys only from trusted server-side code for production workflows. Do not embed keys in public client applications.

{
  "success": true,
  "data": {}
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Workflow

Recommended integration flow

Create a project

Start blank or from a template, then save the project id.

Send a message

Create or revise the HTML preview with natural-language instructions.

Render when ready

Start a render, poll the job, then store the final video URL.

Reference

API endpoints

Expand an endpoint to see request parameters, response fields, and a copyable curl example. Mutating endpoints are marked as POST.

GET/api/v1/meGet the authenticated accountv

Returns the user associated with the API key, including current plan and available render credits.

Request

No body required.

Response fields

iduuid

Authenticated user id.

emailstring

Account email address.

planstring

Current billing plan.

renderCreditsnumber

Available credits.

Example

curl https://parafraim.com/api/v1/me \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY"

GET/api/v1/creditsGet credit balance and recent ledger activityv

Returns total balance, monthly allowance, usage counters, plan limits, and recent credit transactions.

Request

No body required.

Response fields

balancenumber

Available credits.

planstring

Normalized plan id.

monthlyAllowancenumber

Credits granted by the current monthly plan.

usednumber

Credits spent this month net of refunds.

usedTodaynumber

Credits spent today net of refunds.

recentarray

Latest credit transaction records.

Example

curl https://parafraim.com/api/v1/credits \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY"

GET/api/v1/projectsList projectsv

Returns projects owned by the account. Composition HTML is omitted from list responses for compact payloads.

Request

Query parameters

pagenumber

Page number. Defaults to 1.

pageSizenumber

Items per page, clamped between 1 and 50.

Response fields

data[]array

Project summaries with preview availability.

paginationobject

Page, pageSize, total, and totalPages.

Example

curl "https://parafraim.com/api/v1/projects?page=1&pageSize=20" \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY"

POST/api/v1/projectsCreate a projectv

Creates a blank project or seeds it from a template. Project creation is subject to account plan limits.

Request

JSON body

namestringrequired

Project name, 1-100 characters.

descriptionstring

Optional project description, up to 500 characters.

aspectRatio16:9 | 9:16 | 1:1

Preferred format for blank projects.

templateIduuid

Optional template id to copy composition and context from.

Response fields

iduuid

Created project id.

compositionHtmlstring

Current editable HTML composition, empty for blank projects.

hasPreviewboolean

Whether the composition appears renderable.

Example

curl https://parafraim.com/api/v1/projects \
  -X POST \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch video",
    "description": "30 second product launch explainer",
    "aspectRatio": "16:9"
  }'

POST/api/v1/projects/{projectId}/messagesSend a creation or revision requestv

Starts a sandbox task that creates or edits the project composition through natural language. A project can have only one running task at a time.

Request

Path parameters

projectIduuidrequired

Project to create or revise.

JSON body

messagestringrequired

User instruction, 1-10,000 characters.

selectedElementobject

Optional clicked preview element for targeted edits.

selectedElementsarray

Optional list of up to 8 selected preview elements.

Response fields

taskIdstring

Task id for polling or streaming progress.

workspaceIdstring

Sandbox workspace used for the task.

traceIdstring

Diagnostic trace id.

Example

curl https://parafraim.com/api/v1/projects/{projectId}/messages \
  -X POST \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Make the opening more direct and shorten the second scene."
  }'

GET/api/v1/tasks/{taskId}Get a task snapshotv

Returns the persisted task status, assistant message, project snapshot, and latest render job for the task.

Request

Path parameters

taskIdstringrequired

Task id returned by the messages endpoint.

Response fields

statusrunning | completed | error | cancelled

Current task lifecycle state.

lastEventIdnumber

Latest persisted SSE event id.

assistantMessageobject | null

Assistant response linked to the task.

projectobject

Project snapshot including compositionHtml and hasPreview.

Example

curl https://parafraim.com/api/v1/tasks/{taskId} \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY"

GET/api/v1/projects/{projectId}/tasks/{taskId}/streamStream task eventsv

Streams task progress as server-sent events. Use the optional from query parameter to resume after the last event id.

Request

Path parameters

projectIduuidrequired

Project that owns the task.

taskIdstringrequired

Task to stream.

Query parameters

fromnumber

Optional event id offset for resume.

Response fields

textSSE event

Assistant text delta.

html_updateSSE event

Updated project HTML preview.

resultSSE event

Terminal success event.

task_errorSSE event

Terminal error event.

Example

curl https://parafraim.com/api/v1/projects/{projectId}/tasks/{taskId}/stream \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY" \
  -H "Accept: text/event-stream"

POST/api/v1/projects/{projectId}/renderStart a renderv

Precharges estimated credits, asks the sandbox to render the current preview, and returns a render job id.

Request

Path parameters

projectIduuidrequired

Renderable project id.

JSON body

config.widthnumber

Output width, 480-3840. Defaults to 1920.

config.heightnumber

Output height, 270-2160. Defaults to 1080.

config.fpsnumber

Frame rate, 24-60. Defaults to 30.

config.formatmp4 | gif

Output format. Defaults to mp4.

config.qualitydraft | standard | high

Render quality tier. Defaults to standard.

config.includeAudioboolean

Whether audio is included. Defaults to true.

config.includeSubtitlesboolean

Whether subtitles are included. Defaults to true.

Response fields

jobIduuid

Render job id.

traceIdstring

Diagnostic trace id.

Example

curl https://parafraim.com/api/v1/projects/{projectId}/render \
  -X POST \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "format": "mp4",
      "quality": "standard",
      "includeAudio": true,
      "includeSubtitles": true
    }
  }'

GET/api/v1/render-jobs/{jobId}Get a render jobv

Returns render status, progress, video URL, and error details for a render owned by the API key account.

Request

Path parameters

jobIduuidrequired

Render job id returned by start render.

Response fields

Render lifecycle state.

progressnumber

Integer percentage progress.

videoUrlstring | null

Final MP4 URL when complete.

errorstring | null

Failure reason when failed.

Example

curl https://parafraim.com/api/v1/render-jobs/{jobId} \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY"

GET/api/v1/templatesList templatesv

Search and filter reusable templates. Composition HTML is omitted from list responses.

Request

Query parameters

categorystring

Optional exact category filter.

qstring

Optional search across name, description, and category.

pagenumber

Page number. Defaults to 1.

pageSizenumber

Items per page, clamped between 1 and 50.

Response fields

data[]array

Template summaries with hasPreview.

paginationobject

Page, pageSize, total, and totalPages.

Example

curl "https://parafraim.com/api/v1/templates?page=1&pageSize=20&category=news&q=recap" \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY"

POST/api/v1/templates/{templateId}/useCreate a project from a templatev

Copies a template into a new user project and increments template usage count.

Request

Path parameters

templateIduuidrequired

Template to reuse.

JSON body

namestring

Optional project name. Defaults to the template name.

descriptionstring

Optional project description.

Response fields

iduuid

Created project id.

compositionHtmlstring

Template composition copied into the project.

hasPreviewboolean

Whether the copied composition is renderable.

Example

curl https://parafraim.com/api/v1/templates/{templateId}/use \
  -X POST \
  -H "Authorization: Bearer $PARAFRAIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly recap",
    "description": "Founder-focused news recap"
  }'

Troubleshooting

Common error codes

UNAUTHORIZED

The API key is missing, malformed, revoked, or invalid.

INSUFFICIENT_CREDITS

The account does not have enough available credits for the requested operation.

TASK_RUNNING

The project already has an active message task. Wait for it to finish before sending another.

NO_PREVIEW

The project needs a renderable HTML preview before rendering.

VALIDATION

The request body or query parameters failed validation.

PROJECT_LIMIT

The account has reached its project limit for the current plan.

CONCURRENCY_LIMIT

The account has reached its concurrent task limit.

Need a key?

Create an API key from your account settings. The full secret is only shown once, so store it in your server-side secret manager.

Manage keys