Ropewalk API & MCP server docs

Authentication

Every request needs a personal API key in the Authorization header: "Authorization: Bearer rw_live_…". Create and revoke keys in Settings → API (up to 10 per account).

Keys act on your account and spend your wallet. Keep them server-side; never ship them in browser or mobile code.

curl http://ropewalk.ai/api/v1/models -H "Authorization: Bearer rw_live_YOUR_KEY"

Pricing and billing

Every model costs 50% of its in-app price, in coins (1 USD of top-up = 1000 coins). Prices are listed by GET /v1/models: per million tokens for text models, a starting price ("from") for media models whose price depends on settings.

Text: the input plus the output limit is reserved when the request starts, then the unused part is refunded — you pay for tokens actually used. usage.cost_coins in the response shows the final charge.

Media: the price of the chosen settings is reserved at start and settled when the job finishes. Failed jobs are refunded in full. Every charge appears in your wallet history as "API usage".

Models

GET /v1/models lists the models available through the API. Each entry has an id (use it as "model"), type, generation_types, pricing, settings (keys, options, defaults, bounds) and inputs (file inputs such as a reference image). GET /v1/models/{id} returns one model; ids may contain "/".

Settings & files

Media models take three things: a prompt, settings (aspect ratio, duration, quality, number of images…) and inputs — files such as a reference image, a start frame or a voice sample. Each model lists its own setting keys with options and defaults, and its input keys with accepted file types, in GET /v1/models/{id}. Every model also has an "example" field with a ready request.

Settings you leave out use the model defaults. Inputs take a public file URL, or the id of a file uploaded with POST /v1/files (multipart, up to 50 MB) — use that for files on your computer. Pick a model below to see its settings and inputs and get a ready request.

# 1. Upload a file from your computer
curl http://ropewalk.ai/api/v1/files -H "Authorization: Bearer rw_live_YOUR_KEY" -F "file=@photo.jpg"
# → {"id": "6721…", "object": "file", "type": "image", "url": "https://…"}

# 2. Put its id into the model's input (input keys: GET /v1/models/{id} → inputs)
curl http://ropewalk.ai/api/v1/generations \
  -H "Authorization: Bearer rw_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"model": "black-forest-labs/flux-3-image", "prompt": "Turn it into an anime poster", "inputs": {"image": "6721…"}}'

Chat completions

POST /v1/chat/completions follows the OpenAI format: model, messages (system/developer, user, assistant; text content), max_tokens or max_completion_tokens, temperature, top_p and stream. Images in messages are not supported yet.

With stream: true the answer is delivered as standard chat.completion.chunk events followed by [DONE], once it is complete.

from openai import OpenAI

client = OpenAI(base_url="http://ropewalk.ai/api/v1", api_key="rw_live_YOUR_KEY")

reply = client.chat.completions.create(
    model="thinkingmachines/inkling",
    messages=[{"role": "user", "content": "Write a tagline for a coffee shop"}],
)
print(reply.choices[0].message.content)
print(reply.usage)  # includes cost_coins

Image, video, audio and 3D

POST /v1/generations starts a job: {"model", "prompt", "settings": {key: value}, "inputs": {key: url}}. Setting and input keys come from GET /v1/models/{id}. Inputs take public file URLs (or arrays of URLs for multi-file inputs).

The response is 202 with the job. Poll GET /v1/generations/{id} until status is "succeeded" (output.url, valid for one hour) or "failed" (error, coins refunded).

curl http://ropewalk.ai/api/v1/generations \
  -H "Authorization: Bearer rw_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "black-forest-labs/flux-3-image", "prompt": "A red fox in the snow, cinematic light"}'

# → {"id": "6720…", "status": "queued", ...}

curl http://ropewalk.ai/api/v1/generations/6720… -H "Authorization: Bearer rw_live_YOUR_KEY"
# → {"status": "succeeded", "output": {"url": "https://…"}, "cost_coins": 100}

MCP server

Your personal MCP server lives at /v1/mcp (Streamable HTTP) and uses the same key. Tools: list_models, get_model, chat, generate (waits up to ~100 s, then returns a job id), upload_file, get_generation and get_balance. Prices, refunds and limits are the same as the REST API.

Apps sign in with OAuth: add the server address, the app opens a Ropewalk page, you sign in and press Allow — no key to copy. Each connected app gets its own revocable key in Settings → API. Clients without OAuth can send "Authorization: Bearer rw_live_…" or use the personal connector link /v1/mcp/<key>. Step-by-step guides for every app are on the MCP page.

claude mcp add --transport http ropewalk http://ropewalk.ai/api/v1/mcp

{
  "mcpServers": {
    "ropewalk": {
      "url": "http://ropewalk.ai/api/v1/mcp"
    }
  }
}

{
  "mcpServers": {
    "ropewalk": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://ropewalk.ai/api/v1/mcp"
      ]
    }
  }
}

Errors and limits

Errors use the OpenAI shape: {"error": {"message", "type", "code"}}. 400 invalid request, 401 missing or revoked key, 402 insufficient balance, 403 model needs a paid account (first top-up or subscription), 404 unknown model or job, 429 rate limit.

Limits per key: 120 requests per minute and 5 media generations running at once.