Curl vs Python

cURL is ideal for quick, one-off API calls from the command line: simple, immediate, and useful for exploring or debugging endpoints. For production workflows—automating generation in loops, processing and saving results, storing metadata in a database, building scripts or web applications, or integrating generation into larger systems—using a programming language such as Python (or an SDK) provides far better control, error handling, and integration options.

Use cURL for ad-hoc requests and fast debugging. Use Python (or another SDK) when you require automation, conditional logic, parallel processing, persistence, or when integrating generation into applications.

Whatever you can do with cURL, you can also do from Python — but with the added benefit of programmatic control. That includes using loops, retries, concurrency, structured logging, and integrating results with databases or web frameworks. Table: When to use cURL vs Python

Use case	Prefer cURL when	Prefer Python (SDK) when
Quick tests and debugging	You want a one-line request from the terminal	You need to embed requests in an application or script
Automation	Not recommended	Automating batches, retries, and workflows
Processing results	Manual inspection of terminal output	Parse, transform, and persist responses programmatically
Integration	N/A	Integrate with web apps, databases, or pipelines
Concurrency & scaling	Manual or scripting hacks	Native concurrency (threads/async) and task queues

Examples below show equivalent requests using cURL and the Runway Python SDK so you can compare the syntax and typical usage patterns.

Example: GET a task by ID

cURL — quick authenticated GET:

curl https://api.dev.runwayml.com/v1/tasks/486f6eca-6276-4993-bfeb-53cbbbba6f08 \
  -H "Authorization: Bearer {{ YOUR API KEY }}" \
  -H "X-Runway-Version: 2024-11-06"

Python — using the Runway SDK:

# Install the SDK
pip install runwayml

from runwayml import RunwayML

# The env var RUNWAYML_API_SECRET is expected to contain your API key.
client = RunwayML()

task = client.text_to_image.get("486f6eca-6276-4993-bfeb-53cbbbba6f08")
print(task.id)

Never hard-code API keys in source files. Store secrets in environment variables (e.g., RUNWAYML_API_SECRET) or a secure secrets manager.

Example: Create a text-to-image task (POST)

Below is the corresponding cURL POST with a JSON body to create a text-to-image task. cURL POST:

curl -X POST https://api.dev.runwayml.com/v1/text_to_image \
  -d '{
    "promptText": "A serene landscape at sunset",
    "ratio": "1920:1080",
    "seed": 4294967295,
    "model": "gen4_image",
    "referenceImages": [
      {
        "uri": "http://example.com/reference.jpg",
        "tag": "reference"
      }
    ],
    "contentModeration": {
      "publicFigureThreshold": "auto"
    }
  }' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{ YOUR API KEY }}" \
  -H "X-Runway-Version: 2024-11-06"

Successful response (example):

HTTP/1.1 200 OK
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Python (Runway SDK) — same action, expressed with native types and easier programmatic handling:

from runwayml import RunwayML

client = RunwayML()

task = client.text_to_image.create(
    model="gen4_image",
    prompt_text="A serene landscape at sunset",
    ratio="1920:1080",
    seed=4294967295,
    reference_images=[
        {"uri": "http://example.com/reference.jpg", "tag": "reference"}
    ],
    content_moderation={"publicFigureThreshold": "auto"},
)

print(task.id)

Using the SDK allows you to:

Work with native Python objects (lists, dicts) instead of raw JSON strings.
Add retries, error handling, logging, and persistence easily.
Integrate image generation into web applications, background workers, or data pipelines.

Links and references

RunwayML API documentation (reference for endpoints and authentication)
Python packaging — pip

Build a Professional Headshot Generator App with AI

Example: GET a task by ID

Example: Create a text-to-image task (POST)

Watch Video

​Example: GET a task by ID

​Example: Create a text-to-image task (POST)

Watch Video

Example: GET a task by ID

Example: Create a text-to-image task (POST)