DEVELOPERS

AI Workflow API for Image and Video Generation

Discover workflows, inspect their input schema, estimate cost and submit asynchronous runs over HTTP. Retrieve results with a run ID to connect image and video workflows to your application.

Reviewed 2026-09-30

Start with the API contract

Discovery endpoints below are public. Workflow and generation requests require account access and Bearer authentication.

The run lifecycle

Discover a workflow and inspect its input schema
Provide inputs and review the cost estimate
Submit a run with a stable idempotency key
Poll at the supplied interval for a terminal status and outputs

1. Find an available workflow

Create an API key in the developer area after signing in and keep it on your server. Replace the key, workflow ID and input node IDs in these examples with your own values.

export RELAYME_BASE_URL="https://api.relayme.ai"
export RELAYME_API_KEY="<your-api-key>"

curl "$RELAYME_BASE_URL/api/ai-tools/v1/workflows" \
  -H "Authorization: Bearer $RELAYME_API_KEY"

2. Inspect inputs and outputs

# Replace 123 with a workflow ID returned for your account.
export WORKFLOW_ID="123"
curl "$RELAYME_BASE_URL/api/ai-tools/v1/workflows/$WORKFLOW_ID/schema" \
  -H "Authorization: Bearer $RELAYME_API_KEY"

Supply inputs according to inputSchema. Check unsupportedNodes first: browser-only tool nodes may not execute on the server. Output keys correspond to outputSchema.

3. Estimate the run cost

# Replace text-1 with an input node ID from your workflow schema.
curl -X POST "$RELAYME_BASE_URL/api/ai-tools/v1/workflows/$WORKFLOW_ID/estimate" \
  -H "Authorization: Bearer $RELAYME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"text-1":"A clean product photo on a white background"}}'

Review estimatedCost, currency, per-node estimates and assumptions. exact: false means the estimate has uncertainty. Submit a run once its parameters and expected cost are acceptable.

4. Submit and save the run ID

# Create a unique key for each intended run; reuse it for retries of that run.
export RUN_KEY="product:YOUR-PRODUCT-ID:hero-image:v1"
curl -i -X POST "$RELAYME_BASE_URL/api/ai-tools/v1/workflows/$WORKFLOW_ID/runs" \
  -H "Authorization: Bearer $RELAYME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $RUN_KEY" \
  -d '{"inputs":{"text-1":"A clean product photo on a white background"}}'

A newly accepted run returns HTTP 202, Location, Retry-After and data.runId. An idempotent replay may return HTTP 200; read data.runId from that response too. Bind the idempotency key to one business operation: reuse it for network retries and use a new key for a new operation.

5. Poll for the result

export RUN_ID="<runId-from-the-202-response>"
curl "$RELAYME_BASE_URL/api/ai-tools/v1/workflow-runs/$RUN_ID" \
  -H "Authorization: Bearer $RELAYME_API_KEY"

Wait according to Retry-After or retryAfterSeconds. QUEUED, RUNNING and CANCEL_REQUESTED are not terminal. Read outputs on COMPLETED, inspect node errors on FAILED and stop polling on CANCELLED. Signed webhooks are also available when creating a run.

Use RelayMe from your AI agent

Sign in and create an API key in the developer area. Creating a key is free, but generation and workflow runs spend credits, so the account needs enough balance or those requests are refused.
Download the Agent Skill bundle and unzip it: five folders, one skill each, each with a SKILL.md. Put them wherever your agent loads skills from (see your agent’s documentation).
Set RELAYME_API_KEY in the agent’s environment. Keep it in a secret store or on your server, never in a prompt.
Start with one direct generation, for example: Use relayme-creative to generate one 1K, 1:1 product image of a white ceramic mug on a light grey background with Nano Banana. Poll the task until it completes and give me the image link. This spends credits at that model’s rate.

curl -LO https://api.relayme.ai/api/ai-tools/v1/skills.zip
unzip skills.zip -d relayme-skills
ls relayme-skills
# relayme-agent  relayme-chat  relayme-creative  relayme-tasks  relayme-workflows
# each folder contains SKILL.md

export RELAYME_API_KEY="<your-api-key>"

Which calls spend credits

Tool names follow function-tools.json.

Tool	What it does	Spends credits?
`relayme_generate_image`	Direct image generation	Yes: the image model’s per-image rate
`relayme_generate_video`	Direct video generation	Yes: the video model’s per-second rate
`relayme_chat`	Text chat	Yes: the selected text model’s rate
`relayme_run_workflow`	Run a saved workflow	Yes: each generation node in the run
`relayme_estimate_workflow`	Estimate a workflow	No
`relayme_list_models` `relayme_list_workflows` `relayme_get_workflow` `relayme_get_workflow_schema`	Discover models and workflows, read input schemas	No
`relayme_get_task` `relayme_list_tasks` `relayme_get_workflow_run` `relayme_list_workflow_runs`	Check task and run status	No
`relayme_validate_workflow` `relayme_create_workflow` `relayme_update_workflow` `relayme_delete_workflow`	Validate, create, update or delete workflows	No
`relayme_cancel_workflow_run`	Cancel a run	Cancelling is free; calls already sent to a provider may still finish and be billed

What the API does not do

Browser-side tool nodes (image crop, video first and last frame) cannot run on the server. They are listed in unsupportedNodes, and a workflow that depends on them cannot complete through the API.
An estimate is not the final price: nodes that depend on generated upstream content may be estimated with placeholders (exact: false), and the actual charge is what the run records.
A new account has no saved workflows: save one in the workspace or create one through the API before the workflow list returns anything.
Direct image and video generation has no idempotency guarantee; after a timeout, check the task list before resubmitting.
There is no MCP server today, and no Claude or ChatGPT connector; agents connect through the HTTP API and the Agent Skills above.

Frequently asked questions

What does the API support?

Workflow discovery, schemas, estimates, execution and cancellation, plus chat and direct image/video generation. Use the public OpenAPI and individual skills for the current contracts.

Does retrying create another workflow run?

Reuse the original Idempotency-Key for the same workflow-run request to avoid creating a duplicate run. Direct image/video generation does not offer the same idempotency guarantee; check task history after a timeout instead of blindly resubmitting.

Is an estimate the final charge?

No. Nodes that depend on generated upstream content may use placeholders and return exact: false with assumptions. Final cost depends on actual model usage and submitted calls.

Can a cancelled run still incur charges?

Yes. Cancellation stops scheduling subsequent nodes, but tasks already submitted to providers may complete and incur charges. Check inFlightTaskMayComplete and the terminal run status.

Build your integration

Validate a small workflow in the workspace, then connect it to your product through the API.

Create an account Credits and plans Video API selection guide