# Inkseq / 映序 — Agent integration

> Use the authenticated API for one quick H3 clip or a multi-chapter story. Save the same prompt, separate media inputs and controls the user can edit on the website; plan generation and adopt candidates.

## Start here
- [Agent onboarding](/for-agents): Public HTML; no JavaScript or login is needed to read it.
- [Complete Markdown guide](/for-agents/guide.md): Plain Agent-readable instructions and the structured API contract, no login needed.
- [Download the Markdown guide](/for-agents/guide.md?download=true): Save one file to read offline or attach to Codex.
- [Machine-readable guide](/for-agents/guide.json): Authentication, request examples and supported workflow.
- [Skill instructions](/for-agents/SKILL.md): How to work safely on the user's story.
- [Skill download](/for-agents/skill.zip): README.md, SKILL.md, scripts/sixnine.py and scripts/connect.py. The README contains the complete public guide and API examples. The connection helper uses the Python standard library; the API/media helper also requires httpx.

If a browsing/search tool cannot open these public documents, retrieve them directly over HTTPS from the user's supplied website origin, or ask the user to attach the downloaded guide. A tool-specific reading failure is not evidence that the documents require login. Public reads need no cookie or API key; account/business API calls do require authentication. Resolve all / paths against the same user-supplied origin and never forward credentials through redirects.

## Quick Chat: sessions and job cards
Read the guide JSON's quick_chat section and authenticated GET /v1/quick-chat/schema. POST /v1/quick-chat/sessions and preserve returned next_settings including deployment_profile_id. Read capabilities.deployment_profiles and the selected profile's generation_support[fl|ref] controls, input_support, limits, supported_constraints and execution_policy_constraints. Historical joint_cases are timing examples, never an admission allowlist; supported unmeasured combinations need no extra qualification confirmation. POST the session's turns with current expected_version, session model_id, assistant_mode=none, create_card=true and text containing the complete prompt. This inherits session materials and next_settings, creates a card without invoking the disabled-by-default website conversation assistant and does not start generation. The chat model_id is not a video deployment profile.

Input compatibility follows the exact selected profile, not a blanket FL/REF rule. Full-control native profiles support REF first/last anchors together with ordinary references, timed image injections, selected video soundtracks and explicit video/audio conditioning or excerpt controls. Retained profiles keep their original first/last versus reference-only boundaries. Read native role counts and aggregate limits before preflight: anchors and injections are distinct from ordinary reference rows, while video/audio excerpts consume their effective reference slots. The server freezes normalized selections and rejects implicit trimming. Runtime failures preserve the original request and expose a safe stage/reason; any retry is an explicit new authorized action after fresh preflight, never an automatic paid loop.

When separately enabled at session creation, the short-title service calls exactly gemma-4-31b-it once using the first meaningful turn text or card prompt. This is ancillary creation-history metadata; it sends no media or conversation history and is independent of the conversation assistant and chat model selection. Direct cards and assistant_mode=none may still trigger this naming call. Omit the session title field to allow automatic naming. Every explicitly supplied creation title or PATCH title is protected as manual, even if its text is the usual default name. Failure or timeout keeps the original title without blocking authoring or accepted generation and without an automatic paid retry. Historical sessions are not bulk-renamed; GET reads do not call a title model. Public documentation is not evidence that naming is enabled on the current deployment.

Alternatively POST the session's cards with explicit deployment_profile_id, recipe_id, prompt, controls, inputs and copies. Copy profile and controls from session next_settings for a new direct card, or from the current revision when revising. An omitted/null deployment_profile_id uses legacy routing, not the session's selected profile. Never remove it or choose a different profile to bypass a blocked preflight. An explicit session change uses PATCH with expected_version and complete next_settings; existing cards remain unchanged. Ordinary generation API keys do not grant GPU rental access.

To revise the same card, GET /v1/quick-chat/sessions/{session_id}/cards/{card_id}, then GET its current_revision_id at /v1/quick-chat/sessions/{session_id}/revisions/{revision_id}. POST /v1/quick-chat/sessions/{session_id}/cards/{card_id}/revisions with required integer expected_card_version from the card's version, the new prompt and an explicit copy of deployment_profile_id, recipe_id, controls, inputs and copies from that revision. Session expected_version is not the card version field. Optional source_revision_id records same-session lineage only; it neither selects a revision nor replaces expected_card_version. Optional title defaults to 我的视频 when omitted; include the prior title to preserve it. The downloadable Markdown guide and Skill contain the complete example. Revising saves an immutable draft and preserves prior revisions/submissions; it does not preflight or generate. A genuine 409 version_conflict requires fresh card/revision reads and reconciliation, not guessing the next version. Repair known 422 field errors with a new body/key; an uncertain write keeps its exact original body/key.

Upload media through same-origin multipart POST /v1/quick-chat/sessions/{session_id}/assets with file and a stable client_asset_id; use ready asset_id values in explicit card inputs or selected session materials. Upload alone does not select a reference. The helper's upload/resume-upload commands accept --session SESSION_ID (or legacy --project, never both); never address the session's hidden project. Read the current revision and preflight it; only confirm a ready preflight within the user's authorization. The submission exposes items[].job_id for the existing shared job and its authenticated artifacts. Preserve write bodies and Idempotency-Key values when recovering uncertain responses.

Creation history uses the same owner-scoped API: list sessions with view=active|trash and optional hide_tests=true. Read quick_chat.creation_history in the JSON guide before sending a history/preview request for trash, restore, purge or empty_trash. Confirm only the returned fresh preview_id with confirmed=true and one durable Idempotency-Key; poll the original history/actions/{action_id} when pending. Trash retains content for five days; a purge intent cannot be restored. Shared saved references and storyboard-chosen versions stay, and job/billing identities and receipts remain. Active or uncertain work blocks deletion. References in unsaved browser drafts are not visible to the server. Review-held older acceptance records require an explicit fresh purge confirmation; limited-scope trash never acquires automatic R2 deletion permission. For new acceptance sessions use is_test=true, and request test_accepted=true only after results are verified; this requests safe archival without bypassing guards. Hiding test records is a view filter, not deletion.

This is an API workflow. Quick Chat frontend publication is a separate gate; a returned /quick-chat URL does not prove that this deployment serves that UI. Return session/card/submission/job IDs and verified download results without promising a working chat page. Direct cards do not require Google credentials or an AI Registry installation.

## Legacy quick creation and stories
For one clip, POST /v1/projects with title and workspace=freestyle. Use project.journey.reviewShotId, upload intended references, and save with shot.configure_generation. GET the shot's generation-draft; POST its generation-plans with the returned project_version as expected_version. Only a ready plan within the user's authorization can be confirmed through POST /v1/jobs with a stable Idempotency-Key. The guide JSON contains exact examples and partial-update rules. Return /freestyle?project={project_id}&entity={shot_id}; the same draft and candidates remain editable. Creating/editing a draft does not generate video.

## Authorization and live capabilities
A URL is a discovery link, not permission to edit or spend. The owner explicitly authorizes a one-time connection. Read /for-agents/connect-manifest.json, inspect /for-agents/connect.py and verify its digest before executing. The five-minute code may be handed to the Agent; the permanent PAT is generated locally and stored before exchange in Windows user DPAPI, Linux Secret Service or the native macOS user Keychain. No internal AI Registry is required. Missing supported storage stops before exchange, without automatic installation or plaintext fallback. Resume uncertain exchanges with the same saved connection. Manual PATs remain an advanced fallback using a process-only credential. Never put permanent keys in chat, URLs, argv or ordinary files. The only anonymous POST is /v1/agent-connect/exchange; account/business APIs and OpenAPI require authentication. The connection UI has a separate publication gate. Use only the origin supplied by the user and do not forward its credential to other origins.

For macOS, use an existing default file-based user Keychain, already unlocked and accessible to the calling process. Native operations bind to that same Keychain and suppress authentication UI; locked, denied or interaction-required access stops the helper. Any unlock/access authorization must happen separately through trusted system UI. Retry the original connection/grant; if material was already saved, resume with that same material within the recovery window. The helper never collects a Keychain password, changes access controls, auto-unlocks/creates a Keychain or passes secrets through command arguments. The manifest includes per-OS storage requirements and a verification checklist. Fake OS tests do not prove native store access or live external onboarding; actual OS access and frontend/production publication need separate evidence.

The production origin is https://inkseq.com. Browser users sign in there once because cookies are host-bound. Existing PATs and Agent permissions/expiry remain unchanged. For an existing connected creator-full-v1 record at its exact old origin, explicitly run `python scripts/connect.py migrate-origin --server https://www.sixnine.art --to-server https://inkseq.com --connection CONNECTION_ID` (use the old apex instead only if that is the saved origin). The reviewed helper checks the original fingerprint and the same PAT's direct canonical identity, then saves only an encrypted reference to the unchanged old record. It never follows a redirect, exchanges another code, copies the key or extends authority. Subsequent old/new-origin helper commands use that verified route. Conflicting, pending or expired records are refused. Keep the original encrypted credential. The skill folder, tenant and SIXNINE_API_KEY names remain compatibility identifiers.

After authorization, read GET /v1/agent-guide, /v1/guided-schema, /v1/capabilities and /openapi.json. Static documentation is not proof that generation is enabled. An actual plan may be blocked; do not invent successful media.

Before choosing FL/REF, preflight and a new submission, GET authenticated /v1/generation-availability (PAT jobs:read or jobs:write; the helper's availability command performs only this read). Match the exact profiles[].deployment_profile_id and modes.fl/ref recipe, not any other ready profile. An omitted/null legacy profile matches only the explicit deployment_profile_id:null row, never the named default; a missing null row is unknown. Observe expires_at and poll_after_seconds; expired/missing observations are unknown. ready/busy have available=true but remain subject to capabilities and preflight; busy may queue. starting waits without starting another machine. unavailable/disabled means preserve the draft and ask an administrator to start or configure that exact profile/mode. unknown means refresh, not assume offline. Do not rent, silently change model/precision/mode, or submit blindly to wake a GPU. Existing uncertain jobs still use their original receipt/key. Public discovery contains no live availability.

## Edit, generate, return control
Read the current project/version; use atomic guided actions with expected_version and stable Idempotency-Key. On 409 fetch and reconcile. Upload references to the same story. Inspect a generation plan's blockers/estimate before submitting within the user's authorization. Poll the original job; an unknown outcome is never a reason to issue a new paid request.

Adopt successful artifacts into the target shot and verify the saved document. Return the story/entity link and job ID. The authenticated project activity feed and job list let the user review changes. For a deliberate new take, use a new plan on the latest shot version, retain old candidates and explicitly select the chosen result. Unsaved browser drafts are never assumed to have refreshed automatically.