Tryr developer docs: REST API, MCP server and CLI

Tryr turns a product page link into on-model product photos and short product films. This page is for developers and AI agents that use Tryr through the REST API (/agent/v1), the MCP server (/mcp) or the CLI. Tryr is an Agentized.io product.

OpenAPI 3.1 document: https://tryr.app/agent/v1/openapi.json
MCP endpoint (Streamable HTTP): https://tryr.app/mcp
Client setup snippets for MCP clients, REST and CLI: https://tryr.app/agents/en
LLM summary: https://tryr.app/llms.txt · API catalog (RFC 9727): https://tryr.app/.well-known/api-catalog
This page as Markdown: https://tryr.app/developers.md (or request it with Accept: text/markdown)

Authentication

Every call uses the user's personal API key as a bearer token: Authorization: Bearer tryr_sk_....

Sign in on tryr.app and open the panel. Under Agent access, select Create API key. The key is shown only once.
The key belongs to the account: calls spend that account's credits. Keep it private; if it leaks, revoke it in the same section.
Keys work only on accounts that have made a purchase (a plan or a credit top-up).

A missing, invalid or revoked key returns 401 auth_required with WWW-Authenticate: Bearer realm="tryr". A key on an account without a purchase returns 403 purchase_required.

There is no separate sandbox. Reading the account, listing plans, starting a shoot (reading the product page and getting the questions) and building a film plan and quote are free, so an integration can be tested end to end before anything is charged.

Quickstart

Start a shoot from a product page. Put a concrete brief in notes (setting, light, framing, mood, what to avoid; at most 300 characters).

curl -X POST https://tryr.app/agent/v1/shoots \
  -H "Authorization: Bearer tryr_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b7e" \
  -d '{"url":"https://store.example/product","lang":"en"}'

The response is 202 with shoot_id, status and next. Every response carries a next field that names the next step.

Poll the status. wait_seconds (up to 50) holds the request until something changes, so there is no need for fast polling.

curl "https://tryr.app/agent/v1/shoots/SHOOT_ID?wait_seconds=50" \
  -H "Authorization: Bearer tryr_sk_..."

When status is awaiting, ask the user the questions and tell them the cost, then send the answers. An empty answers object uses the defaults. This starts generation and charges credits: every generated image, including the first two previews, costs 2 credits at 1K or 2K and 5 credits at 4K.

curl -X POST https://tryr.app/agent/v1/shoots/SHOOT_ID/answers \
  -H "Authorization: Bearer tryr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"answers":{},"scene_count":4,"resolution":"1K","aspect":"3:4"}'

Show frames with the free 720 px preview (GET /agent/v1/shoots/{id}/frames/{n}/preview; the preview_url in the status is signed and works without the key for 15 minutes). Download full resolution only when the user wants it: GET /agent/v1/shoots/{id}/frames/{n}?size=1k|2k|4k. A download costs only the size difference over what the frame already paid, and the same frame and size is never charged twice.
When scene_count is above 2, POST /agent/v1/shoots/{id}/approve generates the remaining planned scenes (charged per scene; ask the user first).
A film is two steps. POST /agent/v1/shoots/{id}/films returns a plan and a credit quote and charges nothing. POST /agent/v1/shoots/{id}/films/{film}/approve charges the quoted credits once, only after the user approves the price. Then poll GET /agent/v1/shoots/{id}/films/{film}?wait_seconds=50 and download with GET /agent/v1/shoots/{id}/films/{film}/download.

Out of credits (402 plan_gerekli or 402 insufficient_credits): list plans with GET /agent/v1/plans, let the user choose, create a checkout link with POST /agent/v1/checkout, and read the balance with GET /agent/v1/me after they pay. The agent never charges a card; the user pays on the checkout page.

Endpoints

Method and path	Purpose	Cost
`GET /agent/v1/me`	Account, credit balance and current prices	Free
`GET /agent/v1/plans`	Credit plans, billing terms and USD prices	Free
`POST /agent/v1/checkout`	Checkout link for a plan (`package`, `term`)	Free; the user pays on the link
`GET /agent/v1/shoots`	Recent shoots (`limit` up to 100)	Free
`POST /agent/v1/shoots`	Start a shoot from a product URL	Free
`GET /agent/v1/shoots/{id}`	Status, questions, frames and `next` (`wait_seconds`)	Free
`POST /agent/v1/shoots/{id}/answers`	Answer the questions and start generation	2 credits per image (5 at 4K)
`POST /agent/v1/shoots/{id}/approve`	Generate the remaining planned scenes	2 credits per scene (5 at 4K)
`GET /agent/v1/shoots/{id}/frames/{n}/preview`	720 px preview	Free
`GET /agent/v1/shoots/{id}/frames/{n}`	Full resolution frame (`size=1k`, `2k`, `4k`)	Size difference, once
`POST /agent/v1/shoots/{id}/films`	Film plan and credit quote	Free
`POST /agent/v1/shoots/{id}/films/{film}/approve`	Approve the quote and start the film	Quoted credits, once
`GET /agent/v1/shoots/{id}/films/{film}`	Film status and progress (`wait_seconds`)	Free
`GET /agent/v1/shoots/{id}/films/{film}/download`	Completed MP4	Free

Request and response schemas for every operation are in the OpenAPI document.

MCP server

The MCP server lives at https://tryr.app/mcp (Streamable HTTP, stateless: POST only) and takes the same bearer key in the Authorization header. Tools:

tryr_hesap: account, credits and prices. tryr_paketler: credit plans. tryr_kredi_al: checkout link (does not charge).
tryr_cekimler: recent shoots. tryr_cekim_baslat: start a shoot from a product URL. tryr_cekim_durumu: status, questions and frames (wait_seconds).
tryr_cevapla: answer the questions and start generation. tryr_onayla: generate the remaining scenes.
tryr_kare_onizle: free preview. tryr_kare_indir: full resolution frame (charges once per frame and size).
tryr_film_baslat → tryr_film_onayla → tryr_film_durumu → tryr_film_indir: film plan and quote, approval, status, download link.

Setup snippets for individual MCP clients are on https://tryr.app/agents/en.

Errors

Every error from /agent/v1 is an RFC 9457 problem object served as application/problem+json. Unknown paths under /agent, /api and /v1 also return a JSON problem object instead of an HTML page.

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
WWW-Authenticate: Bearer realm="tryr"

{
  "type": "https://tryr.app/developers#errors",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API anahtari eksik, gecersiz ya da iptal edilmis.",
  "instance": "/agent/v1/me",
  "error": "auth_required",
  "message": "API anahtari eksik, gecersiz ya da iptal edilmis.",
  "hint": "Send a personal API key as `Authorization: Bearer tryr_sk_...`; create one in the Tryr panel under Agent access.",
  "docs": "https://tryr.app/developers"
}

error is the stable machine-readable code. Branch on it, not on the text.
detail and message explain the error (Turkish today); hint is the next step in English.
Credit errors add required and available when they are known.

`error`	Status	Meaning and next step
`auth_required`	401	Key missing, invalid or revoked. Send `Authorization: Bearer tryr_sk_...`.
`purchase_required`	403	Keys work only on accounts with a purchase. Ask the user to buy a plan or a top-up.
`admin_required`	403	On a team account only an admin can buy credits.
`not_found`	404	The shoot or film does not exist or belongs to another account.
`route_not_found`	404	No such method and path. Check the OpenAPI document.
`invalid_url`, `url_required`	400	Send the full address of a product page in `url`.
`invalid_json`	400	The body is not valid JSON.
`frames_required`	400	Pick frames whose status is `completed`.
`size_unavailable`	400	That size was not produced for this shoot; ask for a smaller one.
`invalid_package`, `email_required`	400	Use a `package` from `GET /agent/v1/plans`; the account needs a verified email.
`plan_gerekli`, `insufficient_credits`	402	Not enough credits. List plans and offer a checkout link.
`not_awaiting`, `not_ready`, `busy`	409	The shoot or film is in another state. Read the status and follow `next`.
`plan_yok`, `plan_onayi_guncel_degil`	400 or 409	The film plan is missing or changed. Read the film again and approve the current plan and price.
`idempotency_key_reused`	422	The `Idempotency-Key` was used for a different request. Use a new key.
`price_not_configured`, `stripe_not_configured`	503	Checkout is unavailable right now. Retry later.
`internal_error`, `upstream_error`	5xx	Retry later; if it keeps failing, write to support@agentized.io.

Idempotency

Send an Idempotency-Key header (up to 200 characters) on POST requests. Repeating the same key on the same path returns the first response with Idempotent-Replayed: true and does not start a second shoot, film or checkout. Using the key on a different path returns 422 idempotency_key_reused. Responses with a 5xx status are not stored, so a retry after a server error runs again. Frame downloads are idempotent by design: the same frame and size is never charged twice.

Rate limits

The agent API has no per-key request quota today, so responses carry no RateLimit headers. Usage is bounded by the account's credits. Status calls accept wait_seconds (up to 50) so an agent can wait for a change instead of polling in a tight loop. If a request limit is introduced, it will be announced on this page first, responses will carry the IETF RateLimit-Policy and RateLimit headers, and a 429 will include Retry-After.

Versioning and deprecation

The REST API is versioned in the path: /agent/v1. The OpenAPI document states the current version in info.version.
Within v1, changes are additive: new endpoints, new optional fields, new error codes. Clients should ignore fields they do not know.
A breaking change ships under a new path (/agent/v2); v1 keeps working until its sunset date has been announced.
Before an operation is removed it is marked deprecated: true in the OpenAPI document, and its responses carry a Deprecation header (RFC 9745), a Sunset header with the removal date (RFC 8594) and a Link to this section. The change is also listed here.
Nothing is deprecated today.

CLI

The tryr command-line client has not been published to npm yet; until then, use MCP or the REST API. Its commands mirror the API, support --json for machine-readable output and read the key from the TRYR_API_KEY environment variable:

tryr film start <shoot-id> --duration 15 --tier 720p
tryr film approve <shoot-id> <film-id>
tryr film status <shoot-id> <film-id> --wait
tryr film download <shoot-id> <film-id>

Pricing

Prices are in credits; GET /agent/v1/me returns the current prices for the account. On a monthly plan 1 credit is about $0.05. Plans start at $49 a month (Starter, 1,000 credits) and top-ups at $10 ($1 = 20 credits). Full pricing: https://tryr.app/#pricing. Plans are subscriptions that renew until cancelled; the terms are in the Terms of Service.

Support

Questions about the API, bulk use and integrations: info@agentized.io
Support: support@agentized.io
About Tryr · Contact · Terms of Service · Privacy Policy