Idea Developer API

Give your agent access to image and video processing, GPU rendering, and computer-vision tools through an HTTP API.

Get connected

Sign in at the developer dashboard, accept the Developer and API Addendum, and create a secret key. Copy it when it is shown; the full key is only displayed once. Send it in the Authorization: Bearer <secret-key> header from your trusted server.

For connector submissions, select Raw API with API key authentication. Use https://dev.67idea.com/v1 as the base URL and https://dev.67idea.com/docs as the documentation URL.

The dashboard offers a Python SDK installed with pip install idiotproof. The package name remains idiotproof; the product is Idea. The HTTP examples below do not require the SDK.

Python SDK quickstart

Install the idiotproof package on PyPI:

pip install idiotproof

Configure IDEA_SECRET_KEY through your application's secret store or environment. Keep it out of chat, source code, and logs. The SDK reads IDEA_API_BASE_URL if you need to override the default API host.

This example checks catalog access without submitting a GPU job:

import asyncio
from idiotproof import Idea

async def main():
    async with Idea(timeout=300.0) as idea:
        tools = await idea.get_tools()
        for definition in tools:
            print(definition["id"])

asyncio.run(main())

For media work, create a workspace handle with await idea.create_chat(), upload with await idea.upload_file(chat_id, "clip.mp4"), and inspect the discovered tool's schema before calling it. Keep the same chat_id across related operations; save it if another process will continue the work. The SDK creates this opaque handle locally and the service creates its workspace on first use.

The catalog generates async Python methods, such as tools.submit_bobbie_job. Read their current documentation with tools.submit_bobbie_job.__doc__. Exact names and arguments come from the live catalog. For arbitrary names, use await tools.call(tool_name, chat_id, input_dict).

Start with one representative preview. Inspect validation errors and review successful output before processing more media. When a tool returns a job ID, follow that tool's status workflow; do not assume every call returns a background job.

Publish an output workspace path with await idea.media_publish(chat_id, output_path) and deliver its temporary media URL through your application's media UI. Preserve important results with download_media() or download_and_concat(). Published URLs expire, and workspace media is temporary.

Bundled agent guides

The SDK ships detailed guides and reference shaders. This section was checked against idiotproof 0.5.14. Read the guides bundled with the version you install:

from importlib.resources import files

package = files("idiotproof")
print(package.joinpath("README.md").read_text())
print(package.joinpath("docs/api.md").read_text())

Start with the package README, which describes user opt-in and onboarding. Then choose the relevant guide:

For long videos, the SDK uses FFmpeg and ffprobe to split sources beyond 600 decoded frames into ordered parts. A long upload can return multiple workspace URIs instead of a single workspace_uri; preserve their order. Raw HTTP upload clients must handle media preparation themselves.

The SDK exposes Python callables backed by the HTTP API. It does not ship an MCP server or automatically register tools with Muse. A host that accepts only MCP needs an adapter implementing that connection; the custom-server guide explains the approach.

API reference

Download the OpenAPI specification. For connector forms, use https://dev.67idea.com/v1/openapi.json as the specification URL. Both the API root and specification are public; the operations below require an API key.

All paths below are relative to the base URL. JSON requests use Content-Type: application/json.

Use a stable external_user_id for each user of your integration. Uploads, tool runs, and published files must use the same user identity. Workspaces are separated by project, environment, and external user.

Uploads accept supported image and video formats, up to 104,857,600 bytes (100 MiB). Authorizing an upload does not transfer the file; complete the TUS upload before running tools on it.

Base URL and authentication

The developer API is currently served from https://dev.67idea.com/v1. Keep the base URL configurable in clients so it can move to https://api.67idea.com after that hostname, routing, TLS, and observability are provisioned.

Use a secret key only from a trusted server. Never put an idea_sk_* key in a browser bundle or mobile application. Test keys and live keys have separate workspaces and cannot access each other's uploads or tool runs.

Tool requests are sent to the configured MCP gateway with a short-lived JWT minted internally by video_chatbot. API clients use only their developer secret key; they do not mint JWTs or call the MCP gateway directly.

Upload and inspect media

Tool execution may take up to 270 seconds. The tool-run route has a 300-second hosting budget, including authentication, catalog discovery, and persisting the result. Configure clients and proxies to wait at least 300 seconds for POST /v1/tool-runs (for the Python SDK, use Idea(timeout=300.0)). The deployment must support a 300-second function duration; catalog discovery retains its separate 10-second timeout.

For processing beyond this window, use tools that return a job ID and poll their status. A durable tool-run record does not itself move execution to a background worker. A gateway timeout does not guarantee downstream work was canceled; avoid automatically submitting the same work again.

Set placeholders locally; do not check real secrets into source control:

export IDEA_API_BASE="https://dev.67idea.com/v1"
export IDEA_SECRET_KEY="idea_sk_test_<public-id>_<secret>"
export EXTERNAL_USER_ID="your-stable-user-id"
export MEDIA_FILE="/absolute/path/to/video.mp4"

Verify the key before creating resources:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $IDEA_SECRET_KEY" \
  "$IDEA_API_BASE/me"

A successful response contains organization_id, project_id, environment, and scopes. Missing, malformed, unknown, revoked, and expired keys return 401. A valid key without an endpoint's required scope returns 403.

Revoke the key used for the current request without a dashboard session or any additional scope:

curl --fail-with-body --silent --show-error \
  -X DELETE \
  -H "Authorization: Bearer $IDEA_SECRET_KEY" \
  "$IDEA_API_BASE/api-keys/current"

The endpoint never accepts a key ID and can revoke only the authenticated key. After it returns {"object":"api_key","revoked":true}, that secret returns 401 revoked_api_key on subsequent requests. Revocation is irreversible; create a replacement key before revoking if an integration must continue running.

Read the organization billing balance with a key containing usage:read:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $IDEA_SECRET_KEY" \
  "$IDEA_API_BASE/billing/balance"

The balance is returned as an integer string in balance_micros, where one US dollar is 1,000,000 micros. API billing belongs to the developer organization; it is separate from an individual user's web-app balance. reserved_micros is committed to active API operations, while available_micros is the amount available for new work.

Authorize an upload:

FILE_SIZE="$(wc -c < "$MEDIA_FILE" | tr -d ' ')"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $IDEA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"external_user_id\":\"$EXTERNAL_USER_ID\",\"filename\":\"video.mp4\",\"filesize\":$FILE_SIZE,\"filetype\":\"video/mp4\"}" \
  "$IDEA_API_BASE/uploads"

The response contains id, upload_endpoint, upload_token, and tus_metadata. Create the TUS upload with those exact metadata values and the original file bytes. A TUS client library is recommended; the equivalent initial request is:

curl --fail-with-body --silent --show-error --dump-header - \
  -X POST "$UPLOAD_ENDPOINT" \
  -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Length: $FILE_SIZE" \
  -H "Upload-Metadata: filename $FILENAME_B64,filetype $FILETYPE_B64,chatId $WORKSPACE_ID_B64,userId $USER_ID_B64,uploadId $UPLOAD_ID_B64"

Use the returned Location with normal TUS PATCH requests. Do not alter the authorized filename, size, workspace, user, or upload ID. Poll until the API returns succeeded or failed:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $IDEA_SECRET_KEY" \
  "$IDEA_API_BASE/uploads/<upload-id>"

Discover the current catalog before choosing a tool:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $IDEA_SECRET_KEY" \
  "$IDEA_API_BASE/tools"

GET /tools returns the tools and input schemas currently registered by the MCP gateway. Submit any returned tool name with arguments matching its schema. For example, pass an uploaded workspace_uri to ffprobe for the same external user:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $IDEA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ffprobe-<unique-request-id>" \
  -d '{"tool":"ffprobe","external_user_id":"your-stable-user-id","input":{"video_path":"workspace://<workspace-id>/<output-filename>"}}' \
  "$IDEA_API_BASE/tool-runs"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $IDEA_SECRET_KEY" \
  "$IDEA_API_BASE/tool-runs/<run-id>"

Publish media

Publishing is a stable product API and is not part of the dynamic MCP tool catalog. Publish a file from the same external-user workspace to receive short-lived display and download URLs:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $IDEA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id":"your-stable-user-id","media_path":"workspace://<workspace-id>/<output-filename>","ttl_seconds":1800}' \
  "$IDEA_API_BASE/media/publish"

ttl_seconds is optional, defaults to 7200, and must be an integer from 1 to 7200. This endpoint requires media:read; it does not require tools:read or tools:execute. The API resolves the workspace from the authenticated project, environment, and external_user_id, and rejects paths for any other workspace.

API keys need uploads:create, uploads:read, tools:read, tools:execute, runs:read, media:read, and usage:read for this complete flow. Keys created before a scope was introduced are not silently granted it; replace them if they do not contain it. Revoked keys stop authorizing new API requests immediately; already-issued upload tokens remain valid only until their short expiration.

Retries and errors

Supply an Idempotency-Key on tool-run requests. Reuse the same key and request body when retrying the same operation; reusing a key with different input returns 409 idempotency_conflict. Use a new key for each new operation.

Authentication failures return 401; missing scopes return 403. Invalid requests return 400. Metered operations may return 402 for insufficient funds. Inspect both the HTTP response and the returned run status and error fields. A timeout does not prove the GPU operation stopped; inspect the existing run before submitting new work.

Current prices and available credit depend on the account and billing configuration. Check the dashboard and the organization balance endpoint applicable to your integration. Contact support@4014labs.com for integration assistance.