Model Inference Quickstart

Models use the same run lifecycle. The current catalog is focused on video generation: choose a model, submit a run, and retrieve the result when it finishes.

Protoface Studio is the browser editor; it is separate from the inference API, which does not expose Studio projects or scenes.

Prerequisites

Create an API key in the Protoface dashboard. If the key uses scopes, it needs runs:write to submit work and runs:read to check the result. Set it in your shell:

export PROTOFACE_API_KEY="sk_live_..."

1. Submit a run

This example generates an eight-second video with MiniMax H3:

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: first-video-001" \
  -d '{
    "prompt": "A wide shot of a sailboat crossing a quiet bay at sunrise.",
    "duration_seconds": 8,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

The response contains the run ID, its queue status, and the credits reserved for it. This is an excerpt:

{
  "id": "run_...",
  "object": "run",
  "model": "minimax-h3",
  "operation": "video.general",
  "status": "queued",
  "queue_position": 0,
  "credit_estimate": {
    "estimated_credits": 29,
    "maximum_reserved_credits": 29
  },
  "status_url": "/v1/runs/run_.../status",
  "response_url": "/v1/runs/run_..."
}

Credit prices can change. Use the estimate returned by the API instead of hard-coding the value shown here.

2. Check the status

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

Poll until status is completed, failed, or canceled. Use a delay between requests; the status endpoint is intended for polling.

3. Retrieve the result

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

For a run with one video output, video contains the file. This is an excerpt:

{
  "id": "run_...",
  "status": "completed",
  "progress": 100,
  "video": {
    "url": "https://...",
    "content_type": "video/mp4",
    "file_name": "output.mp4"
  },
  "error": null
}

See Runs for the full outputs array and lifecycle.

Models

Read model capabilities and request fields.

Runs

Handle inputs, polling, cancellation, and retries.

Get Started

Model Inference

Realtime

Account

Reference

Model Inference Quickstart

Prerequisites

1. Submit a run

2. Check the status

3. Retrieve the result

Next

Models

Runs

​Prerequisites

​1. Submit a run

​2. Check the status

​3. Retrieve the result

​Next

Models

Runs

Prerequisites

1. Submit a run

2. Check the status

3. Retrieve the result

Next