Dify custom tool from OpenAPI: import the Sume API schema

To call the Sume API from Dify as a custom tool, open Integrations > Tools, choose Swagger API, and paste a trimmed copy of Sume's OpenAPI schema that keeps three operations: createVideoGeneration, getVideoGeneration, and getApiJobResult. Dify generates the tool interface from the schema and names each tool after its operationId.

Dify facts come from its Tools, Tool node, HTTP Request node, Agent, and plugin pages; Sume facts come from the API reference, Video Generation, Jobs and results, and Authentication docs and the OpenAPI document, all read on 2026-09-27. Sume has no Dify plugin: the tool makes plain HTTPS calls to api.sume.com. Downloading and browsing the spec is covered in Sume API OpenAPI spec.

Which Sume operations should the Dify tool keep?

Dify can also import a schema from a URL, and Sume's live schema is https://api.sume.com/reference/json. Importing all of it would give the tool every operation in the schema, paid generation routes included. A video tool needs three:

How do I trim Sume's schema to those operations?

Download the schema with the docs' command, curl https://api.sume.com/reference/json -o sume-openapi.json. Then keep the three operations, every component schema they reference, and the two securitySchemes, and paste the output file into the Swagger API dialog:

import json, re

KEEP = {"createVideoGeneration", "getVideoGeneration", "getApiJobResult"}
REF = re.compile(r"#/components/schemas/([\w.-]+)")
spec = json.load(open("sume-openapi.json"))
paths = {}
for path, ops in spec["paths"].items():
    for method, op in ops.items():
        if isinstance(op, dict) and op.get("operationId") in KEEP:
            paths.setdefault(path, {})[method] = op
schemas = spec["components"]["schemas"]
todo, keep = REF.findall(json.dumps(paths)), set()
while todo:
    name = todo.pop()
    if name not in keep:
        keep.add(name)
        todo += REF.findall(json.dumps(schemas[name]))
trimmed = {
    "openapi": spec["openapi"], "info": spec["info"], "servers": spec["servers"],
    "paths": paths,
    "components": {"securitySchemes": spec["components"]["securitySchemes"],
                   "schemas": {name: schemas[name] for name in keep}},
}
json.dump(trimmed, open("sume-video-tools.json", "w"), indent=2)

Where does the Sume API key go?

Every call needs the key as Authorization: Bearer or x-api-key, never both: a request with both is rejected with 401 unauthorized. The trimmed schema declares both schemes, bearerAuth and apiKey. Dify's docs say that if a tool requires authentication, you select an existing credential or create a new one in the Tool node or the agent's tool settings. Dify's Tools page doesn't describe the Swagger API tool's own auth fields, so confirm the credential goes out as one of Sume's two headers.

• Check it without spending: call getVideoGeneration with a made-up id. 401 means the key did not arrive or is invalid; 404 means the key worked and the job is not in your workspace.
• Keep the key out of the schema text, the prompt, and input fields. Dify says hidden input fields are not secret and to use environment variables for API keys.
• If a key appears in logs or chat history, rotate it.

How does a Dify agent get the finished video?

Over several turns. createVideoGeneration returns a job id at once, and video generation typically takes 30 seconds to several minutes, so have the agent report the id and check back in a later message instead of looping inside one request. Dify's Maximum Iterations setting caps how many reasoning-and-action cycles one request gets, and higher values add latency and token costs.

• model and prompt are required; sume/auto lets Sume pick the model. Tell the agent to leave out size, seed, and non-empty provider.options, which v1 models reject.
• When status is completed, call getApiJobResult: each entry in data.result.artifacts has a url on media.sume.com to show the user.
• Don't show unsigned_urls from getVideoGeneration. They point at GET /v1/videos/{id}/content, which the docs call with your API key.

When is an HTTP Request node the better fit?

When the call is a fixed workflow step rather than the model's choice. The HTTP Request node's API Key auth with the Bearer subtype adds Authorization: Bearer <token>, and Secret-type environment variables are masked in workflow run logs and in the node's request log. Its retry settings can retry a failed request up to 10 times, so send an Idempotency-Key header on POST /v1/videos: a replay returns the original job instead of starting a second one. Polling rules are in How to poll a video generation job status API.