Do it quickly, but do it right

A recent client project involved a mobile app for initiating asynchronous conversations: you record a video to start a discussion, scroll through videos that have already been posted, and respond with a video to any discussion starter or reply. Great. Except that their AI agent had shamelessly invented a POST /medias/like, a DELETE /playlist/item, and two or three parameters that never existed on our end. The code was clean, well-commented, and elegant, but it couldn’t work.

The need for a “skill” was glaringly obvious. In other words, a folder of text files that the AI assistant reads before coding, so it knows what it’s talking about.

A quick aside on the environment—since it must be addressed

You know us—AI isn’t exactly our cup of tea. We wrote an entire article on
the carbon footprint of AI and video, and the conclusion doesn’t exactly make us fans of 5-gigawatt data centers.

Except that an agent that tries to guess our API gets it wrong, tries again, guesses again, tries yet again, and eventually spits out code that a human will have to fix by hand. Thirty back-and-forths where three would have sufficed. By that measure, writing good documentation was undoubtedly the most sensible thing we could do.

What We Put In It

It is here and it is public:
github.com/Streamlike/streamlike-integration-skill

The input file first answers the question that determines everything else: which door to enter through. There are three options. The web services for reading the catalog—designed specifically for that purpose and fast. The REST API for writing, managing, and sending files—but never, ever from a mobile app or a browser, because an API key grants its owner full access. The JavaScript SDK when you want a playlist player that works in just four lines of code.

Next come the references, one per topic: the fifteen web services with their actual response formats, the API conventions, the sixty-nine player parameters, security, statistics, RSS feeds, and sitemaps.

And then there are the pitfalls—the ones that aren’t written down anywhere because no one thinks to write them down.

• The “page” parameter in web services is an offset, not a page number. “pagesize=10&page=1” returns items 1 through 10, and you might wonder why the second page looks so much like the first.
• ‘sortorder’ expects “up” or “down.” If you type “desc“, like any sensible person would, you get a 404. While writing the skill, we realized we hadn’t documented this anywhere.
• web service errors are returned as an HTML page with a 404 code. No JSON, no message. Your parser chokes, and you spend twenty minutes trying to figure it out.

A developer who has read this writes code that works. A developer who hasn’t read it writes code that seems to work, which is much more of a hassle.

Three Recipes: From Requirements to Code

We’ve launched a recipe book that already features three examples and will be updated regularly:

• A scrollable mobile app—the one from the client who started it all: where to store “likes” and rejected videos (on your end, not ours, and the article explains why), when to pause players, and how to keep your users’ data plans from blowing up.
• A web TV service: playlists, search capabilities that go as far as transcripts, a video sitemap for SEO, and a ready-to-use playlist player.
• Automatic media ingestion: upload a file, track its encoding without having to guess, add subtitles, and publish it…

Included is a file of examples that run as-is, along with a demo video.

You don’t need an account to try it out. It’s also the fastest way to find out if the problem is with your code or with us.

The tool we’re most excited about

Our OpenAPI description is 2.5 MB. No wizard can process it all at once, and when it tries, it leaves half your project behind. So the skill includes a small utility that retrieves only what’s needed:

scripts/openapi_lookup.py show /medias --method post
scripts/openapi_lookup.py search "audio track"

It downloads the file on its own and always checks the published version. Our endpoints change, and the skill keeps up without you having to update it.

Finally, a few words of honesty

None of this replaces our documentation, let alone our support. You’ll still need an account, a company_id, and an API key—which we’ll create for you. And your assistant will continue to spout nonsense about the rest of the world, but there’s nothing we can do about that.

On Streamlike, however, it will have read the manual.

All the links in one place:

• The skill: github.com/Streamlike/streamlike-integration-skill (1),
• the JavaScript and PHP SDKs: github.com/Streamlike,
• the API documentation: api.streamlike.com/openapi.json,
• the web services documentation: cdn.streamlike.com/openapi.json.

Upload the folder to your tool, describe your project, and see what happens. And if your agent comes up with yet another endpoint, let us know—it’ll mean we’re missing a page.

(1) Another bit of honesty: “Skill made by Madame Claude.” Yes, that’s what we call it around here.