> ## Documentation Index
> Fetch the complete documentation index at: https://docs.techforgeinnovate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Job

> Queue a project-backed job and return the created job record immediately.

# 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

<ParamField body="job_type" type="string" required>
  Workflow type. Valid values are `ai_talking_video`, `video`, `tts`, `image`, `photo_qc`, `pdf`, and `ai_image_generation`.
</ParamField>

<ParamField body="template_id" type="string">
  Recommended project UUID for template-driven workflows. The controller resolves `template_id` before `project_id`.
</ParamField>

<ParamField body="project_id" type="string">
  Alternative project or source ID. This is also used for `ai_image_generation` flows.
</ParamField>

<ParamField body="values" type="object">
  Project-specific input values. Entries can be plain strings or asset objects such as `{ "image_url": "..." }` or `{ "audio_url": "...", "effects": [...] }`.
</ParamField>

<ParamField body="version" type="number">
  Workflow version. The current studio sends `2` for template-driven jobs.
</ParamField>

<ParamField body="session_id" type="string">
  Client session identifier used by the studio for correlated notifications.
</ParamField>

<ParamField body="background_music" type="string | null">
  Optional background music URL for video workflows. Use `null` or omit this field to render without background music.
</ParamField>

<ParamField body="background_volume" type="number">
  Optional background music volume for video workflows. Valid range is `0` to `1`.
</ParamField>

<ParamField body="background_start" type="number">
  Optional background music start offset in seconds for video workflows. Minimum value is `0`.
</ParamField>

Any additional fields are stored in the job `input` payload and interpreted by the downstream worker for the selected `job_type`.

## Recommended request shape

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

```bash theme={null}
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

```bash theme={null}
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

<ResponseField name="message" type="string" required>
  Queue acknowledgement. The current implementation returns `Job update accepted and processing.`
</ResponseField>

<ResponseField name="job.uuid" type="string" required>
  Unique job UUID.
</ResponseField>

<ResponseField name="job.job_status" type="string" required>
  Initial job state. New jobs are created as `QUEUED`.
</ResponseField>

<ResponseField name="job.job_type" type="string">
  Persisted workflow type.
</ResponseField>

<ResponseField name="job.template_id" 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`.
</ResponseField>

Example response:

```json theme={null}
{
  "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](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.