Skip to main content
POST
/
jobs
/
v2
Create Job
curl --request POST \
  --url https://api.techforgeinnovate.com/jobs/v2 \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "job_type": "<string>",
  "template_id": "<string>",
  "project_id": "<string>",
  "values": {},
  "version": 123,
  "session_id": "<string>",
  "background_music": {},
  "background_volume": 123,
  "background_start": 123
}
'
{
  "message": "<string>",
  "job.uuid": "<string>",
  "job.job_status": "<string>",
  "job.job_type": "<string>",
  "job.template_id": "<string>"
}

​
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

​
job_type
string
required
Workflow type. Valid values are ai_talking_video, video, tts, image, photo_qc, pdf, and ai_image_generation.
​
template_id
string
Recommended project UUID for template-driven workflows. The controller resolves template_id before project_id.
​
project_id
string
Alternative project or source ID. This is also used for ai_image_generation flows.
​
values
object
Project-specific input values. Entries can be plain strings or asset objects such as { "image_url": "..." } or { "audio_url": "...", "effects": [...] }.
​
version
number
Workflow version. The current studio sends 2 for template-driven jobs.
​
session_id
string
Client session identifier used by the studio for correlated notifications.
​
background_music
string | null
Optional background music URL for video workflows. Use null or omit this field to render without background music.
​
background_volume
number
Optional background music volume for video workflows. Valid range is 0 to 1.
​
background_start
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

curl -X POST "https://api.techforgeinnovate.com/jobs/v2" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $TFI_API_KEY" \
  -d '{
    "template_id": "468ea7a0-66e1-4357-a760-236e54167f3e",
    "job_type": "ai_talking_video",
    "version": 2,
    "session_id": "fb8f8b96-cfef-4bf7-a819-a46d2afb4d1c",
    "values": {
      "headline": "Launch in minutes",
      "voiceover": {
        "audio_url": "https://cdn.example.com/audio/launch.mp3"
      },
      "avatar": {
        "image_url": "https://cdn.example.com/images/avatar.png"
      }
    }
  }'

​
Video editor background audio example

curl -X POST "https://api.techforgeinnovate.com/jobs/v2" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $TFI_API_KEY" \
  -d '{
    "template_id": "468ea7a0-66e1-4357-a760-236e54167f3e",
    "job_type": "video",
    "version": 2,
    "session_id": "fb8f8b96-cfef-4bf7-a819-a46d2afb4d1c",
    "background_music": "https://cdn.example.com/audio/bgm.mp3",
    "background_volume": 0.1,
    "background_start": 0,
    "values": {
      "headline": "Launch in minutes",
      "hero_image": {
        "image_url": "https://cdn.example.com/images/hero.png"
      }
    }
  }'

​
Response

​
message
string
required
Queue acknowledgement. The current implementation returns Job update accepted and processing.
​
job.uuid
string
required
Unique job UUID.
​
job.job_status
string
required
Initial job state. New jobs are created as QUEUED.
​
job.job_type
string
Persisted workflow type.
​
job.template_id
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: 
{
  "message": "Job update accepted and processing.",
  "job": {
    "uuid": "15a6331b-3837-4ae8-8fa7-d3ead3388d77",
    "user_id": "c95a2ab1-7c10-4a03-9d25-55f905d2b6f0",
    "template_id": "468ea7a0-66e1-4357-a760-236e54167f3e",
    "input": {
      "template_id": "468ea7a0-66e1-4357-a760-236e54167f3e",
      "job_type": "ai_talking_video",
      "version": 2,
      "session_id": "fb8f8b96-cfef-4bf7-a819-a46d2afb4d1c",
      "values": {
        "headline": "Launch in minutes"
      }
    },
    "values": {
      "headline": "Launch in minutes"
    },
    "job_status": "QUEUED",
    "job_type": "ai_talking_video",
    "credit_used": "0"
  }
}

​
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.