Fotor OpenAPI SDK

Async-first Python SDK for the Fotor OpenAPI. No MCP, no S3 -- just an API key.

Setup

1. Ensure SDK installed (run once, skipped if already present):

   python scripts/ensure_sdk.py
   

2. Ensure FOTOR_OPENAPI_KEY is set in environment.

Scripts

scripts/ensure_sdk.py

Cross-platform (Windows / macOS / Linux) script to check and install fotor-sdk from PyPI. Run before any task. Outputs JSON with status and version.

• No args — install only if missing (fast, no network if already installed)
• --upgrade — upgrade to latest PyPI version

scripts/run_task.py

Execute one or more Fotor tasks from JSON. Handles client init, polling, and progress.

Single task:

echo '{"task_type":"text2image","params":{"prompt":"A cat","model_id":"seedream-4-5-251128"}}' \
  | python scripts/run_task.py

Batch (array):

echo '[
  {"task_type":"text2image","params":{"prompt":"A cat","model_id":"seedream-4-5-251128"},"tag":"cat"},
  {"task_type":"text2video","params":{"prompt":"Sunset","model_id":"kling-v3","duration":5},"tag":"sunset"}
]' | python scripts/run_task.py --concurrency 5

Options: --input FILE, --concurrency N (default 5), --poll-interval S (default 2.0), --timeout S (default 1200).

Output: JSON with task_id, status, success, result_url, error, elapsed_seconds, tag.

Reference Files

Read these before selecting a model or constructing parameters:

• references/image_models.md -- image model IDs, T2I/I2I capabilities, resolution/ratio support
• references/video_models.md -- video model IDs, T2V/I2V/SE/MI capabilities, duration, audio
• references/parameter_reference.md -- full function signatures and parameter tables for all 8 task types

Workflow

1. Run python scripts/ensure_sdk.py to confirm SDK availability.
2. Verify FOTOR_OPENAPI_KEY is set.
3. Read the appropriate model reference to choose model_id.
4. Quick path -- pipe JSON into scripts/run_task.py (works for both single and batch).
5. Custom path -- write inline Python using the SDK directly (see examples below).
6. Check result_url in output. Chain image_upscale if higher resolution needed.

Available Task Types

For full parameter details (defaults, on_poll, **extra), read references/parameter_reference.md.

Inline Python Examples

When scripts/run_task.py is insufficient (custom logic, chaining, progress callbacks):

Client Init

import os
from fotor_sdk import FotorClient
client = FotorClient(api_key=os.environ["FOTOR_OPENAPI_KEY"])

Single Task

from fotor_sdk import text2image
result = await text2image(client, prompt="A diamond kitten", model_id="seedream-4-5-251128")
print(result.result_url)

Batch with TaskRunner

from fotor_sdk import TaskRunner, TaskSpec
runner = TaskRunner(client, max_concurrent=5)
specs = [
    TaskSpec("text2image", {"prompt": "A cat", "model_id": "seedream-4-5-251128"}, tag="cat"),
    TaskSpec("text2video", {"prompt": "Sunset", "model_id": "kling-v3", "duration": 5}, tag="sunset"),
]
results = await runner.run(specs)

Video with Audio

from fotor_sdk import text2video
result = await text2video(client, prompt="Jazz band", model_id="kling-v3",
                          audio_enable=True, audio_prompt="Smooth jazz")

TaskResult

result.success          # bool: True when COMPLETED with result_url
result.result_url       # str | None
result.status           # TaskStatus: COMPLETED / FAILED / TIMEOUT / IN_PROGRESS / CANCELLED
result.error            # str | None (e.g. "NSFW_CONTENT")
result.elapsed_seconds  # float
result.metadata         # dict (includes "tag" from TaskRunner)

Error Handling

• Single task: catch FotorAPIError (has .code attribute).
• Batch: check result.success per item; runner never raises on individual failures.
• NSFW: appears as error="NSFW_CONTENT" in TaskResult.

SDK Internals (debugging)

Image sizes auto-calculated from aspect_ratio + resolution (see references/parameter_reference.md).

Enable debug logging: logging.getLogger("fotor_sdk").setLevel(logging.DEBUG)