Jobs

Morface generation and transformation requests run as asynchronous jobs.

Submit a job

Route:

POST /api/v1/jobs/submit/{jobType}

The request body must include job_type, model, and input. job_type must match the route segment.

Recommended client construction:

BASE_URL=https://www.morface.ai/api/v1
SUBMIT_URL=$BASE_URL/jobs/submit/$job_type

The submit body follows the same public job contract used by the Morface studio workflow. Typical fields include:

• job_type
• model
• input.source
• input.target
• input.reference
• input.audio
• webhook

Public media fields only accept public http/https URL strings. Multi-file slots accept arrays of URL strings. Job params such as compressionQuality should also be placed inside input.

Read job status

Route:

GET /api/v1/jobs/{uuid}/status

The status response is your polling fallback and may include:

• the current job state
• detailed status text
• structured error information when the job fails
• result readiness flags

Cancel a job

Route:

POST /api/v1/jobs/{uuid}/cancel

Cancellation is scoped to the same authenticated user. A key cannot cancel another user's job.

Fetch the result

Route:

GET /api/v1/jobs/{uuid}/result

When the job is ready, the result route returns a signed URL for the generated output. Webhook payloads intentionally do not include the signed result URL.

Ownership and retry behavior

• Submit and read routes are scoped to the authenticated API key owner.
• Use Idempotency-Key on submit when your backend may safely retry.
• Keep status polling as a fallback even if you rely on webhooks.

Related pages

• Webhooks
• Error and Idempotency Rules