Skip to main content
POST
Create Job

Create Job

Queues a new job for the authenticated account. The controller stores your full request body as the job input, resolves the referenced project or source, and pushes the job to the async worker queue. This is the primary endpoint for API-key-driven brand marketing workflows.

Request

string
required
Workflow type. Valid values are ai_talking_video, video, tts, image, photo_qc, pdf, and ai_image_generation.
string
Recommended project UUID for template-driven workflows. The controller resolves template_id before project_id.
string
Alternative project or source ID. This is also used for ai_image_generation flows.
object
Project-specific input values. Entries can be plain strings or asset objects such as { "image_url": "..." } or { "audio_url": "...", "effects": [...] }.
number
Workflow version. The current studio sends 2 for template-driven jobs.
string
Client session identifier used by the studio for correlated notifications.
string | null
Optional background music URL for video workflows. Use null or omit this field to render without background music.
number
Optional background music volume for video workflows. Valid range is 0 to 1.
number
Optional background music start offset in seconds for video workflows. Minimum value is 0.
Any additional fields are stored in the job input payload and interpreted by the downstream worker for the selected job_type. For brand-marketing integrations, the common pattern is:
  • Discover a project with GET /api/provider/projects/active
  • Inspect its expected fields with GET /api/provider/projects/:projectId/mapping-fields
  • Send template_id, job_type, version, session_id, and values

Example request

Video editor background audio example

Response

string
required
Queue acknowledgement. The current implementation returns Job update accepted and processing.
string
required
Unique job UUID.
string
required
Initial job state. New jobs are created as QUEUED.
string
Persisted workflow type.
string
Resolved source ID for the job. This maps to a template UUID for most workflows and to an image prompt ID for ai_image_generation.
Example response:

Status codes

  • 201 Created when the job is queued
  • 400 Bad Request when the project or source ID cannot be resolved
  • 401 Unauthorized when the key is missing or invalid

Notes

  • Poll api/jobs-get with the returned job.uuid.
  • The controller accepts more than talking-video jobs even though the public studio often uses this route for template-driven video and talking-video flows.
  • Ownership is enforced through the API key when resolving projects and reading jobs.
  • For video and ai_talking_video version 2, background_music, background_volume, and background_start are accepted as top-level optional fields.