yino.ai Media API
How to Call
Use whatever HTTP tool you have — curl, Python requests, Node fetch, or built-in HTTP.
These APIs are designed for agents: errors include explanations and doc links, and batch mode reduces round trips.
Preflight
echo $YINO_API_KEY — must be set. Get one at https://yino.ai/settings (API Keys section).echo ${YINO_API_BASE_URL:-https://yino.ai} — defaults to production. Set YINO_API_BASE_URL=http://localhost:3000 for local dev.
If either fails, stop and tell the user.
Auth
Every request needs: Authorization: Bearer $YINO_API_KEY
Step 1: Discover Capabilities
Always start here. Don't assume model names or parameters — discover them:
curl "${YINO_API_BASE_URL:-https://yino.ai}/api/agent/capabilities" \
-H "Authorization: Bearer $YINO_API_KEY"
This returns all available models and tools with their endpoints, tags, and doc links. Models change over time — always discover first.
Each capability includes a doc field (e.g. /docs/models/seedream-4-5.mdx). Fetch the doc to learn input parameters before calling any endpoint:
curl "${YINO_API_BASE_URL:-https://yino.ai}{doc_field_value}"
Doc URL convention: Any URL ending in .mdx returns raw Markdown — the same content humans see on the website, but readable by you directly. Each doc starts with a breadcrumb (e.g. > [docs](/docs) / [models](/docs/models) / seedream-4-5) with links you can follow to navigate to parent pages or sibling docs.
Step 2: Key Patterns
Projects: A project groups related generations and enables visual preview pages. Use projects in two situations:
- Upfront — the user's task clearly involves multiple related generations (storyboard, style exploration, multi-shot video). Suggest: "Would you like me to create a project so you can preview all the results together?"
- Retroactive — you've already generated several related items without a project. Suggest: "I've generated a few related pieces — want me to organize them into a project?" Then create a project and use
PATCH /api/agent/generations/:id with project_id to assign existing generations to it.
After creating a project, immediately share the project link with the user: ${YINO_API_BASE_URL}/projects/{project_id} — they can open it to watch progress and browse results as you generate.
Read references/project-preview.md for project workflow, preview block types, incremental update strategies, and examples.
Async + Polling: Model endpoints return task_id(s), not results. Poll with sleep + exponential backoff to balance between polling too frequently and waiting too long.
curl "${YINO_API_BASE_URL}/api/agent/generations/status?ids=id1,id2" \
-H "Authorization: Bearer $YINO_API_KEY"
Each generation has status (pending → processing → done / failed) and output.url when done.
Polling tips:
- Poll manually one call at a time. Use
sleep between polls with exponential backoff — do NOT write automated loop scripts, they block your execution environment and prevent you from doing useful work in between.
- While waiting, do useful work: if you have multiple batches in flight, check another batch, update the project preview with results that are already done, or inform the user of progress.
- Tell the user the current status between polls.
Batch mode: When you have multiple items, always use batch. One request with 10 items beats 10 separate requests. Wrap inputs in {"items": [...]} (up to 20).
File upload: When you need to provide a file (image, audio), upload it first:
curl -X POST "${YINO_API_BASE_URL}/api/agent/upload" \
-H "Authorization: Bearer $YINO_API_KEY" \
-F "file=@path/to/file"
Returns a URL you can pass to other endpoints. Max 10MB, supports images and audio.
Error Handling
All error responses are designed to be agent-friendly. Every error includes:
error — human-readable message explaining what went wrongdoc — link to the relevant documentation
When you hit an error, fetch the doc link for detailed guidance. Most issues are self-diagnosable from the error message alone.
Caching
If the user repeats the same type of task 3-4 times, ask if they'd like you to save the common parameters as a note in their workspace. Don't save anything without asking.
