To make a video that explains how your API works, follow one real request from start to finish instead of touring your endpoints. Pick the single call most developers make first, then draw it as a journey: the developer's code, the authentication header, your edge, the service that does the work, the response, and what happens when it fails. Write about 300 to 450 words of narration (two to three minutes at 150 spoken words a minute), one scene per hop, and put the actual request and response on screen as short, readable snippets. End with where to get a test key. Check every status code, header name and field against your real API, because a developer will copy what they see.

What developers want from an API video

Developers do not watch API videos for entertainment. They watch to answer three questions quickly: what does this do, what does a call look like, and what will go wrong. Your reference docs already answer all three, in alphabetical order and at length. The video's job is to answer them in the order someone actually meets them, once, so the reference makes sense afterwards.

That rules out two common formats. The endpoint tour ("we have quotes, shipments, labels, tracking and webhooks") is a slower table of contents. The screen-recorded terminal session, typing curl commands live, is fine for a tutorial but poor for an explainer, because the interesting part (what happens on your side) is invisible in a terminal.

A drawn request journey shows the part the terminal hides. The request becomes an object that moves between labelled boxes, and the viewer sees where auth is checked, where the work happens and where the rate limit lives. If you want a hands-on coding tutorial instead, see how to make a developer tutorial video without screen recording.

The scene structure

Seven scenes is right for a two to three minute video. If you have async behaviour, such as a webhook firing later, it deserves its own scene, because it is the part developers most often misunderstand.

Worked example: a shipping-quote API

Take a made-up API that returns shipping prices for a parcel. Here is the narration for the core scenes, with what each draws.

Scene 1, the job. "You send us a parcel's size, weight and two addresses. We send back what every carrier would charge to move it, in about half a second." Draws: a parcel, two pins on a map, three price tags appearing.

Scene 2, the caller. "Your code makes one POST request to slash v1 slash quotes, with the parcel and the two addresses in the body." Draws: a small code card.

POST /v1/quotes
Authorization: Bearer sk_test_your_key_here
Content-Type: application/json

{ "weight_g": 1200, "from": "M5V 2T6", "to": "H2X 1Y4" }

Scene 3, auth. "The key goes in the Authorization header. Our edge checks it before anything else happens. Test keys start with sk underscore test and never touch real carriers." Draws: the request arriving at a gate labelled Edge, a tick against the key.

Scene 4, the work. "Inside, we ask each carrier for a rate in parallel, convert everything to your currency, and sort by price." Draws: the request splitting into three arrows to three carrier boxes, coming back together.

Scene 5, the response. "You get a 201 with a list of quotes. The field you want is quote id: you will pass it back when you buy the label." Draws: the response card, with quote id circled.

Scene 6, failure. "Two errors cover most first days. A 401 means the key is missing or wrong, so check the header. A 429 means you are calling too fast; wait for the number of seconds in the Retry-After header, then try again." Draws: two red cards beside the gate.

Scene 7, what next. "Buying a label is the same shape: one POST with your quote id. When the carrier scans the parcel, we call your webhook. Get a test key from the dashboard and try the call above." Draws: a webhook arrow coming back the other way, labelled Later.

That is about 200 words of narration for the main beats, plus a short intro and outro, which lands near two minutes.

The sample above is the general version of the same idea. A single request becomes the main character, and each hop gets its own drawn moment with one sentence of narration.

Rules for code on screen

Code in an explainer is a picture, not a listing. Treat it that way.

• Ten lines at most per card. If the real request body has twenty fields, show the four that matter and say "plus optional fields in the docs".
• Never a real key. Use an obviously fake placeholder like sk_test_your_key_here. People pause videos and copy what they see, and a real-looking key also teaches people to paste keys into places they should not.
• Real field names, exactly. If the API says weight_g, the video does not say weight. A mismatch costs someone twenty minutes on day one.
• Say the path, do not spell it. "POST to slash v1 slash quotes" sounds odd written down but is how developers say it, and how the narration should read.
• One language per video. Pick the language most of your users call from, or show raw HTTP, which every developer reads.

Make it

1. 1

   Pick the first call

   Look at your logs or support tickets and find the call new developers make first. That request is your main character; ignore every other endpoint for now.

2. 2

   Write one line per hop

   Caller, auth, the work, response, failure, what next. One or two sentences each, in the order the request travels, about 300 to 450 words in total.

3. 3

   Paste it and keep your wording

   In openCanviz, paste the narration with Keep my wording on so technical terms come through exactly, set a target of two to three minutes, and pick whiteboard style, where each hop draws as it is described.

4. 4

   Replace any code the draft invented

   Open each scene with code or a label on it and replace it with your real path, header and field names. Generated drafts get the shape right and the spelling of identifiers wrong.

5. 5

   Check the errors against production

   Make the failing calls yourself and confirm the status codes and header names match what the video says. Then record your own voice over it if you can; developers trust an engineer's voice.

6. 6

   Put it above the reference

   Embed it at the top of your getting-started page, not on the homepage, with the same request copied out in text underneath so nobody has to transcribe from a video.

Where this sits in your docs

An API explainer is the first thing on the getting-started page and nowhere else in the reference. It does not replace the quickstart; it makes the quickstart readable. Put the request from the video directly below it as copyable text, so developers move from watching to running in one scroll.

For a broader product audience (buyers, not implementers), the same API often needs a different video about the job it does, with no code at all. That is closer to a SaaS product explainer. If the audience is your own team, explaining how the system behind the API is built, see how to make an engineering architecture explainer for your team.

Common questions

How long should an API explainer video be? Two to three minutes for the core request journey. If you have several distinct flows (payments and refunds, say), make one short video per flow rather than one long one, and link each from the relevant guide.

Should I show a real terminal or real code editor? For an explainer, no. A drawn code card stays readable at any size and does not date when your editor theme or CLI output changes. For a follow-along tutorial, a real terminal is fine.

How do I keep it up to date when the API changes? Keep the video at the level of the request journey and the two or three fields that matter, which change rarely. When a field is renamed, edit that one scene and export again rather than remaking the video.

What about versioning? Put the version in the path on screen (v1, v2) and say it once. If a major version changes the journey, make a new video and keep the old one on the old version's docs.

Do I need to explain authentication in detail? Only the part the developer touches: which header, what the key looks like, the difference between test and live. Token rotation, scopes and OAuth flows deserve their own short video if your API uses them.