U-Gen.AI/Docs
Dashboard

Jobs API

The Jobs API is the core of U-Gen. Use it to create video generation jobs, monitor progress through the pipeline, and retrieve the final output.

Pipeline Stages

A job progresses through stages: prepare → agents → init → generation → concat → audio → captions → complete. Track progress via the current_stage and progress_percent fields.

Create Job

Create a new UGC video generation job. Credits are reserved upfront and settled on completion.

POST/api/v1/jobs

• Credits are reserved at creation and released/consumed when the job completes or fails.

• If idempotency_key is omitted, a UUID is auto-generated. Same key + same params returns the existing job.

• If persona_id is omitted, a random persona is auto-assigned.

• When custom_script is provided, script_structure, script_tone, key_selling_points, and cta_text are ignored.

• Veo models fix segment_duration at 8s. Kling models allow 3–10s.

• Aspect ratio 1:1 is only supported by Kling models.

• QAI mode sets the quality threshold. Retries are configured separately (max_retries_keyframe, max_retries_video: 0–5 each, defaults 1/0).

Required

ParameterType
product_nameREQ
string

Parameters

ParameterType
product_image_urlREQ
string (URL)
segment_countREQ
integer
video_resolution
string
Default: standard
aspect_ratio
string
Default: 9:16
segment_duration
integer
Default: 8
interaction_mode
string
Default: holdable
environment_description
string
key_selling_points
string[]
cta_text
string
custom_script
string
script_structure
string
Default: standard_5phase
script_tone
string
Default: conversational
caption_style
string
Default: tiktok_karaoke
custom_caption_options
object
music_mood
string
music_volume
number
Default: 0.15
custom_music_id
string
voice_settings
object
qai_mode
string
Default: lenient
human_review_max_rejections
integer
Default: 0
human_review_budget
string
Default: accept_best
stop_at_stage
string
idempotency_key
string

Video Generation

ParameterType
video_model
string
Default: veo3_fast

Content & Script

ParameterType
persona_id
string

Captions

ParameterType
captions_enabled
boolean
Default: true

Music

ParameterType
music_enabled
boolean
Default: true

Voice

ParameterType
elevenlabs_voice_id
string

Quality Assurance (QAI)

ParameterType
qai_enabled
boolean
Default: true

Human Review (HITL)

ParameterType
human_review
string
Default: off

Pipeline Control

ParameterType
failure_behavior
string
Default: accept_best

Delivery

ParameterType
webhook_url
string (URL)

Request Example

curl -X POST https://api.u-gen.ai/api/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "product_name": "Premium Wireless Headphones",
    "product_image_url": "https://example.com/headphones.jpg",
    "segment_count": 3,
    "interaction_mode": "holdable",
    "video_model": "veo3_fast",
    "script_tone": "enthusiastic",
    "music_mood": "upbeat",
    "qai_enabled": true
  }'

Suggest Fields

Get AI-powered field suggestions based on your product. Free — no credits consumed.

POST/api/v1/jobs/suggest-fields

• This endpoint is free — no credits are consumed.

• Uses AI vision to analyze the product image and suggest script-related fields.

• Returns: key_selling_points, cta_text, environment_description, and custom_script.

Parameters

ParameterType
product_nameREQ
string
product_image_urlREQ
string (URL)
persona_id
string
interaction_mode
string
segment_count
integer

Request Example

curl -X POST https://api.u-gen.ai/api/v1/jobs/suggest-fields \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "product_name": "Wireless Headphones",
    "product_image_url": "https://example.com/headphones.jpg"
  }'

AI Suggest Workflow

Call Suggest Fields first with a product image, then use the response to pre-fill key selling points, CTA, environment, and script in the Create Job request.

Get Job

Retrieve job status with progress_percent, segments, and all output URLs.

GET/api/v1/jobs/{jobId}

• The gateway enriches the response with a progress_percent field (0–100).

• During the generation stage, progress is proportional to completed segments.

• Poll this endpoint every 5–10 seconds to track job progress.

• Segments are included in the response with individual status and output URLs.

Parameters

ParameterType
jobIdREQ
string (UUID)

Request Example

curl -X GET https://api.u-gen.ai/api/v1/jobs/YOUR_JOB_ID \
  -H "X-API-Key: YOUR_API_KEY"

List Jobs

List all jobs for the authenticated tenant with optional status filtering.

GET/api/v1/jobs

Parameters

ParameterType
status
string
page
integer
Default: 1
page_size
integer
Default: 20

Request Example

curl -X GET https://api.u-gen.ai/api/v1/jobs?status=completed&page=1&page_size=10 \
  -H "X-API-Key: YOUR_API_KEY"

Cancel Job

Cancel a pending or processing job. Reserved credits are released.

DELETE/api/v1/jobs/{jobId}

Parameters

ParameterType
jobIdREQ
string (UUID)

Request Example

curl -X DELETE https://api.u-gen.ai/api/v1/jobs/YOUR_JOB_ID \
  -H "X-API-Key: YOUR_API_KEY"

Pause Job

Pause a processing job. The pipeline stops after the current stage completes.

POST/api/v1/jobs/{jobId}/pause

Parameters

ParameterType
jobIdREQ
string (UUID)

Request Example

curl -X POST https://api.u-gen.ai/api/v1/jobs/YOUR_JOB_ID/pause \
  -H "X-API-Key: YOUR_API_KEY"

Resume Job

Resume a paused job. Processing continues from where it left off.

POST/api/v1/jobs/{jobId}/resume

Parameters

ParameterType
jobIdREQ
string (UUID)

Request Example

curl -X POST https://api.u-gen.ai/api/v1/jobs/YOUR_JOB_ID/resume \
  -H "X-API-Key: YOUR_API_KEY"

Retry Job

Retry a failed job from a specific pipeline stage. Credits are re-reserved if needed.

POST/api/v1/jobs/{jobId}/retry

• Restarts the pipeline from the specified stage. All subsequent stages are re-processed.

• If the job was completed or failed, credits are re-reserved automatically.

• If restart_from_stage is omitted, retries from the stage where the job failed.

Parameters

ParameterType
jobIdREQ
string (UUID)
restart_from_stage
string

Request Example

curl -X POST https://api.u-gen.ai/api/v1/jobs/YOUR_JOB_ID/retry \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "restart_from_stage": "generation"
  }'

Retry Credits

Retrying a job re-reserves credits from the restart stage onward. Make sure you have sufficient balance before retrying.

List Keyframes

Retrieve all keyframe images for a job with QAI scores and status.

GET/api/v1/jobs/{jobId}/keyframes

Parameters

ParameterType
jobIdREQ
string (UUID)

Request Example

curl -X GET https://api.u-gen.ai/api/v1/jobs/YOUR_JOB_ID/keyframes \
  -H "X-API-Key: YOUR_API_KEY"

List Videos

Retrieve all video segments for a job with generation status and URLs.

GET/api/v1/jobs/{jobId}/videos

Parameters

ParameterType
jobIdREQ
string (UUID)

Request Example

curl -X GET https://api.u-gen.ai/api/v1/jobs/YOUR_JOB_ID/videos \
  -H "X-API-Key: YOUR_API_KEY"