Morface API Reference

Use this page as the top-level reference for Morface Public API V1. For implementation details, continue into the dedicated pages for authentication, jobs, webhooks, and retry policy.

Base URL

https://www.morface.ai/api/v1

Use this as the shared public API base. Job submit paths are derived by appending:

/jobs/submit/{jobType}

For example:

https://www.morface.ai/api/v1/jobs/submit/image-face-swap

Auth and headers

• Authorization: Bearer <api_key> is required on every public API request.
• Public API routes do not use session cookies.
• Write routes return X-Request-Id.
• POST /api/v1/jobs/submit/{jobType} accepts Idempotency-Key.
• Submit bodies must include job_type and model.
• job_type must match the {jobType} route segment.
• Submit bodies must include an object field named input.

Response envelope

All public API responses reuse the same envelope:

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Error responses use code: -1 and keep the failure reason in message.

Endpoint map

Jobs

Media contract

Submit routes use the public media contract described in docs/job-api.md.

At the boundary, media slots such as source, target, reference, and audio live under input and may be sent as:

• a single string
• a string array

Each media value must be a public http/https URL reachable by Morface.

Job-type routed submit calls

Use job_type in two places on submit:

• In the URL path: /jobs/submit/{jobType}
• In the request body: job_type

These two values must match. This keeps the public API easy to assemble from a shared BASE_URL while still letting the server validate the intended job route.

Idempotency

Submit requests support Idempotency-Key with a 24-hour retention window.

• Same key + same body: returns the original response
• Same key + different body: returns 409
• No key: each retry may create a new job

Webhook delivery

Submit payloads may include:

{
  "webhook": {
    "url": "https://example.com/webhooks/morface",
    "secret": "whsec_demo",
    "events": ["job.completed", "job.failed", "job.cancelled"]
  }
}

Retry schedule for non-2xx responses or timeouts:

1. Immediate first attempt when the job reaches a terminal state
2. Retry after 1 minute
3. Retry after 5 minutes
4. Retry after 30 minutes
5. Retry after 6 hours

Related pages

• Authentication
• Jobs
• Webhooks
• Error and Idempotency Rules