Runs

A run is one model inference request. Submission reserves the quoted credits and returns a run ID immediately.

Lifecycle

A run moves through these states:

queued: accepted and waiting to start.
running: generation is in progress.
completed: output is ready.
failed: generation failed and the reservation was released.
canceled: canceled by the caller.

Submit

Send a flat JSON body to POST /v1/run/{model_id}. The model entry defines which fields the body accepts.

curl -X POST https://api.protoface.com/v1/run/minimax-h3 \
  -H "Authorization: Bearer $PROTOFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-shot-001" \
  -d '{
    "prompt": "A slow camera move around a ceramic lamp in a quiet studio.",
    "duration_seconds": 8,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

Use an Idempotency-Key when a request may be retried. Reusing the key with the same request returns the original run. Reusing it with a different request returns a conflict.

Media inputs

Models that accept images, video, or audio can take:

An asset_... ID returned by POST /v1/assets or a previous run.
A public HTTPS URL.
A data URI.

Use a URL or data URI for one-off input. Use an asset ID to reuse media across runs. The field names and maximum number of files vary by model. Check GET /v1/models/{model_id} before building the request.

Poll status

Use the lightweight status endpoint while the run is active:

curl https://api.protoface.com/v1/runs/run_.../status \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

Wait between polls. queue_position is available while a run is queued and may be null after it starts.

Retrieve a result

curl https://api.protoface.com/v1/runs/run_... \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

The outputs array contains the full result. When there is exactly one video output, the response also includes it in video for convenience.

Cancel

curl -X POST https://api.protoface.com/v1/runs/run_.../cancel \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

Canceling a queued run releases all reserved credits. Once a run starts, canceling it still charges the full reserved amount. Completed and failed runs return 409 if you try to cancel them.

List runs and events

List recent runs:

curl "https://api.protoface.com/v1/runs?limit=20" \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

For detailed progress or debugging, read the ordered event stream:

curl https://api.protoface.com/v1/runs/run_.../events \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

Models

Read model capabilities and request fields.

Errors

Handle rate limits, conflicts, and failed requests.

Get Started

Model Inference

Realtime

Account

Reference

Lifecycle

Submit

Media inputs

Poll status

Retrieve a result

Cancel

List runs and events

Next

Models

Errors

​Lifecycle

​Submit

​Media inputs

​Poll status

​Retrieve a result

​Cancel

​List runs and events

​Next

Models

Errors

Lifecycle

Submit

Media inputs

Poll status

Retrieve a result

Cancel

List runs and events

Next