Generate an OpRun#

After a developer has deployed an op to your gyoza cluster, it becomes an OpDefinition on the server. You can now instantiate an OpRun from it to actually execute the op with your inputs.

All interactions happen through the gyoza server REST API. This guide uses curl for the examples, but any HTTP client works the same way.

See also

Full API reference with all endpoints and schemas: REST API.

Prerequisites#

We will use http://localhost:5555 as the server URL, my-secret-token as the API key and classify-op as the OpDefinition name throughout this guide.

Check the input and output specs#

Before creating a run you need to know what inputs the op expects and what outputs it produces. You can fetch the OpDefinition by name using:

GET /definitions/{name}

For our classify-op example:

curl http://localhost:5555/definitions/classify-op \
  -H "X-API-Key: my-secret-token"

The response includes (among other fields) the input_specs and output_specs sections:

{
  "id": "classify-op",
  "version": "1.0.0",
  "input_specs": {
    "image_path": {"type": "string", "required": true},
    "top_k":      {"type": "int",    "required": false, "default": 3}
  },
  "output_specs": {
    "label":      {"type": "string"},
    "confidence": {"type": "float"}
  }
}

This tells you that image_path is required (a string) and top_k is optional (defaults to 3). Your run request must satisfy these constraints. The output_specs section lists the fields the op produces, which is also where you find the field names you can pre-fill with upload URLs (see Delivering file outputs).

Create the run#

To create an OpRun, send a POST to the definition’s runs endpoint:

POST /definitions/{name}/runs

For our classify-op example, providing the inputs that match the spec above:

curl -X POST http://localhost:5555/definitions/classify-op/runs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-token" \
  -d '{
    "inputs": {
      "image_path": "/remote/path/photo.jpg",
      "top_k": 3
    },
    "priority": 5
  }'
inputs

The input payload for the op. Required fields must be present and types must match the input_specs, otherwise the server returns a 400 error.

priority

Optional. Scheduling priority for the execution of the op. OpRuns with higher priority are executed first by the scheduler.

outputs

Optional. Partial outputs template, pre-fill an output field with an upload URL to have the file it produces delivered there. See Delivering file outputs below.

If you need to run a specific version of the OpDefinition, you can append a version query parameter to the request, if you don’t specify a version, the server will use the latest version of the definition by default.

curl -X POST "http://localhost:5555/definitions/classify-op/runs?version=1.0.0" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-token" \
  -d '{"inputs": {"image_path": "/remote/path/photo.jpg"}}'

The response is the full OpRun object, including its id, save it, you will need it to monitor, cancel, or retry the run:

{
  "id": "a1b2c3d4-...",
  "state": "PENDING",
  "priority": 5,
  "progress": 0,
  "current_attempt": 1,
  "image": "myregistry/classify-op:1.0.0",
  "inputs": {"image_path": "/remote/path/photo.jpg", "top_k": 3},
  "outputs": {},
  "op_definition": "classify-op",
  "createdAt": "2026-03-02T20:00:00Z",
  "updatedAt": "2026-03-02T20:00:00Z"
}

The run starts in PENDING state and will be picked up by a worker automatically.

Delivering file outputs#

Ops that produce large files declare them as output fields holding a local path (see Build a Gyoza Op). Since gyoza only transports JSON and knows nothing about your storage, you tell each run where to deliver those files by pre-filling the output field with an upload URL (e.g. a presigned S3/GCS PUT URL, signed with your credentials). The field names come from the definition’s output_specs:

curl -X POST http://localhost:5555/definitions/segment-op/runs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-token" \
  -d '{
    "inputs": {"image_url": "https://bucket.example/photo.jpg?X-Sig=..."},
    "outputs": {"mask": "https://bucket.example/results/mask.tif?X-Sig=..."}
  }'

After the op runs, gyoza uploads the produced file to that URL and the final output holds the file’s canonical URL (the query string with the signature is stripped):

{
  "state": "COMPLETED",
  "outputs": {"mask": "https://bucket.example/results/mask.tif"}
}

Fields without a pre-filled URL are returned exactly as the op produced them. The template survives retries, and neither the server nor the worker ever holds storage credentials, the URL is opaque data to them.

Next steps#