API Documentation

Check that the key is valid. No fields.

response

• ok: true

Your key, your account, your wallet balance and a 30 day usage summary (calls, orders, charges in cents).

response

• key { id, name, last4, scopes, created_at, last_used_at }
• customer { id, email, name }
• wallet { currency, balance_cents }
• usage { window_days, requests, orders, credits_cents }

curl -H "Authorization: Bearer $KEY" https://mystage.film/api/v1/me

The key's request history: route, method, status, order_id when the call created an order, and credits_cents for what it debited. Cursor pagination.

body / query

• cursor string?: next_cursor of the previous page
• limit int?: 1..100 (default 20)

response

• data: [{ id, created_at, route, method, status_code, order_id, credits_cents, product_name, order_status, delivered_at, currency }]
• has_more: boolean
• next_cursor: string | null

curl -H "Authorization: Bearer $KEY" "https://mystage.film/api/v1/usage?limit=50"

The categories of the showcase, with their slug, English and Greek name and how many videos each has.

response

• data: [{ slug, name, name_el, video_count }]

curl -H "Authorization: Bearer $KEY" https://mystage.film/api/v1/video-categories

The showcase videos, all or one category. Each item has poster_url, video_url (HLS), duration_seconds, categories (names), category_slugs and product_id: the product that orders a video like this one, or null for an example only. Filters: category, tag, q, aspect. Media needs a Referer header.

body / query

• category string?: a category slug
• tag string?
• q string?: text search
• aspect string?: landscape | portrait | square
• cursor string?
• limit int?: 1..100

response

• data: [{ id, title, title_el, subtitle, subtitle_el, categories, category_slugs, subcategory, hashtags, tags, aspect, duration, duration_seconds, video_url, poster_url, product_id, product_slug }]
• product_id: null = an example only, not orderable
• has_more, next_cursor

curl -H "Authorization: Bearer $KEY" "https://mystage.film/api/v1/videos?category=restaurants&limit=20"

One showcase video, the same shape as a list item. 404 not_found for an unknown id.

response

• ShowcaseVideo: the same shape as a list item
• 404 not_found

Ready made AI models to answer a model-picker field (the model id) or a person-spec field in library mode. Filter: gender.

body / query

• gender string?: female | male

response

• data: [{ id, number, collection, gender, attributes, thumb_url }]

One library model with its front, back, side and portrait images.

response

• Model with signed front, back, side and portrait images

Your catalog: title (EN, EL), subtitle, prices per length, duration_prices, aspect_ratios, has_storyboard, categories, tags, an example video and poster. Filters: category, tag, q, aspect, length_seconds. Cursor pagination.

body / query

• category string?: a category slug
• tag string?
• q string?: text search
• aspect string?: landscape | portrait | square (or 16:9, 9:16, 1:1)
• length_seconds int?
• cursor string?
• limit int?: 1..100

response

• data: [{ id, slug, title { en, el }, subtitle { en, el }, description, native_aspect, aspect, aspect_ratios, resolution_choice, duration_options, video_seconds, prices: [{ length_seconds, price_cents, price_1080_cents, subtitles_price_cents, revision_price_cents }], duration_prices, has_storyboard, categories, subcategories, tags, hashtags, example_video_url, example_poster_url, example_duration_seconds, currency, created_at }]
• has_more, next_cursor

curl -H "Authorization: Bearer $KEY" "https://mystage.film/api/v1/products?category=restaurants"

One product by id or slug, all details. has_storyboard true means the order stops once for a storyboard the customer approves; false means it goes straight to the finished video.

body / query

• productId: the product id or its slug

response

• Product: one product, all details
• has_storyboard: true = a storyboard to approve, false = straight to the video

The answer fields the product asks for: type, label, required, options, show_if, upload slots, model_library and api_settable. Build your form from here; leave out hidden fields and fields with api_settable false (the default applies).

response

• product_id, languages, aspect_ratios
• fields: [{ key, type, required, label, help, options, min, max, show_if, require_one_of, upload, groups, person_attributes, model_library, api_settable }]

Requests a presigned URL for one intake file. Body: purpose "intake", content_type (image/jpeg, image/png, image/webp, audio/mpeg, audio/mp4), size_bytes (up to 50 MB, exact). PUT to url with exactly the returned headers before it expires (10 minutes). Keep the upload_id for the order answers.

body / query

• customer_id uuid: your own customer id (GET /me)
• purpose "intake"
• content_type enum: image/jpeg | image/png | image/webp | audio/mpeg | audio/mp4
• size_bytes int: 1..52428800, exact

response

• upload_id: reference it in the order answers
• url: PUT the bytes here
• method "PUT"
• headers { content-type }: send exactly these
• expires_at (10 minutes)

curl -X POST -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" -d '{"customer_id":"…","purpose":"intake","content_type":"image/jpeg","size_bytes":48123}' \
  https://mystage.film/api/v1/uploads

curl -X PUT -H "content-type: image/jpeg" --data-binary @photo.jpg "$UPLOAD_URL"

Creates the order and charges your wallet in one transaction. Body: customer_id, product_id, length_seconds (from the prices), aspect (optional, from aspect_ratios), add_ons { subtitles, extra_formats, resolution, duration_seconds } (optional, only what the product offers), answers (the intake form fields; files as upload_id), uploads (list of upload_id), review (optional). complimentary is not available through the API. 402 insufficient_credit when the balance is not enough: nothing is created or charged.

body / query

• customer_id uuid: your own customer id
• product_id uuid: from GET /products or a video product_id
• length_seconds int: one of the product prices length_seconds
• aspect enum?: one of the product aspect_ratios (default: native)
• add_ons object?: { subtitles?, extra_formats?, resolution?, duration_seconds? } only what the product offers
• answers object: the intake form fields; files as upload_id
• uploads string[]: the upload_ids used in answers
• review enum?: required | default

response

• 201 Order: status "received", total_cents, add_ons
• 402 insufficient_credit: nothing created, nothing charged
• 422 *_not_offered: a choice the product does not sell

curl -X POST -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" -d '{"customer_id":"…","product_id":"…","length_seconds":15,"answers":{},"uploads":[]}' \
  https://mystage.film/api/v1/orders

Your orders, newest first. Filters: status, created_after (ISO), customer_id. Cursor pagination.

body / query

• cursor string?
• limit int?: 1..100
• customer_id uuid?
• status enum?: received | awaiting_approval | changes_requested | in_production | delivered | failed | cancelled | awaiting_balance
• created_after string?: ISO timestamp

response

• data: [Order]
• has_more, next_cursor

curl -H "Authorization: Bearer $KEY" "https://mystage.film/api/v1/orders?status=delivered"

One order: status (received, awaiting_approval, changes_requested, in_production, delivered, failed, cancelled, awaiting_balance), details, add ons, total_cents, cancellation_requested.

response

• Order: id, status, customer_id, product_id, length_seconds, aspect, add_ons, total_cents, currency, complimentary, cancellation_requested, created_at

Files a cancellation REQUEST for our staff (201, status pending). Body: reason (required, 10 characters or more). Production is not stopped and nothing is refunded automatically: our team decides the request and any refund. The order can still be delivered meanwhile.

body / query

• reason string: why you cancel, 10 to 1000 characters

response

• 201 { order_id, status: "pending" }: a request for our staff; production is not stopped, nothing is refunded automatically
• 409 cancellation_pending | not_cancellable

Only for products with has_storyboard true: the current storyboard, its version_id, status and scenes with images (links valid 10 minutes). 404 storyboard_not_ready before it is ready.

response

• order_id, version_id, version_number, status, revisions_allowed
• scenes: [{ scene_index, label, caption, image_url }]
• images_expire_at (10 minutes)
• 404 storyboard_not_ready

Approves the storyboard on behalf of the customer; production continues. Body: version_id from GET storyboard.

body / query

• version_id uuid: from GET storyboard

response

• { order_id, version_id, status: "approved" }: production continues

Requests changes on scenes. Body: version_id and changes, a list of scene_index and comment (10 to 2000 characters). A round may be paid from the wallet (402 revision_payment_failed); 15 second videos can only be approved.

body / query

• version_id uuid: from GET storyboard
• changes array: [{ scene_index int, comment string (10..2000) }]

response

• 201 { order_id, version_id, status: "changes_requested" }
• 402 revision_payment_failed | 409 revisions_unavailable

Only when delivered: a download URL for the finished MP4 and expires_at (10 minutes). Do not store the link, ask again. Download the file once and host it on your own server.

response

• url: MP4 download link
• expires_at (10 minutes): ask again for a fresh link
• filename
• 409 not_delivered | order_cancelled

Registers a webhook for your own orders. Body: url (public https, port 443), events (order.* only), description (optional). The response holds the signing secret, shown only this once. Up to 5 endpoints per account.

body / query

• url string: public https, port 443
• events string[]: order.created | order.paid | order.production_started | order.storyboard_ready | order.awaiting_approval | order.changes_requested | order.delivered | order.failed | order.cancelled
• description string?

response

• WebhookEndpoint + secret (whsec_…, shown only once)

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/in","events":["order.delivered","order.storyboard_ready"]}' \
  https://mystage.film/api/v1/webhook-endpoints

Your webhook endpoints, newest first. The secret is never shown again.

response

• data: [{ id, url, description, events, status, disabled_reason, created_at, updated_at }]

One of your webhook endpoints.

response

• WebhookEndpoint

Changes url, events or description, or disables and enables it again (status active or disabled).

body / query

• url string?
• events string[]?
• description string?
• status enum?: active | disabled

response

• WebhookEndpoint

Deletes an endpoint that never received a delivery. If it has delivery history, disable it instead.

response

• { id, deleted: true }
• 409 endpoint_has_deliveries: disable it instead

Sends a signed webhook.ping test event now and reports whether the endpoint answered 2xx.

response

• { delivered, http_status, error_code }

A new signing secret, shown only in this response. Events are signed with it from now on.

response

• WebhookEndpoint + new secret (shown only once)