{ "openapi": "3.1.0", "info": { "title": "Yuanjing AI API", "version": "1.6.0", "description": "Public developer API. Asset registration and private temporary R2 upload do not execute generation or charge credits. Planning and workflow-job endpoints retain their documented non-executing boundary." }, "x-yuanjing-agent-compatibility": { "contract_version": "yuanjing-agent-compatibility-v1", "claim_scope": "protocol_only", "client_certification_performed": false, "matrix_path": "downloads/skills/yuanjing-ai/references/agent-compatibility.json" }, "servers": [ { "url": "https://yuanjing-ai.com" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "yj_live_...", "description": "Developer API Key。完整 Key 仅在 Device token 交换时返回一次；勿写入 URL、日志或聊天。" }, "accountBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "YJ_...", "description": "网站账户授权码。仅用于 Agent Skill 页连接批准、手动 Key 管理，不可替代 Developer Key 调用 /api/v1。" } }, "schemas": { "GenerationRequest": { "type": "object", "required": [ "client_request_id", "prompt", "expected_credits" ], "additionalProperties": false, "properties": { "client_request_id": { "type": "string", "maxLength": 128 }, "prompt": { "type": "string", "maxLength": 4000 }, "model": { "type": "string", "enum": [ "gpt-image-2.0", "gpt-image-2-vip", "nano-banana-2", "nano-banana-pro" ] }, "aspect_ratio": { "type": "string", "default": "1:1" }, "image_size": { "type": "string", "enum": [ "1K", "2K", "4K" ] }, "n": { "type": "integer", "minimum": 1, "maximum": 4 }, "confirmed": { "type": "boolean", "description": "Set true after explicit approval. When omitted/false, approval_policy_id must identify an enabled, active, connection-bound bounded policy." }, "approval_policy_id": { "type": "string", "pattern": "^apol_", "description": "Default-off alternative to confirmed=true. The server atomically reserves policy credits/outputs against this exact stable request and quote fingerprint." }, "expected_credits": { "type": "integer", "minimum": 0, "description": "Exact credits shown to and approved by the user. The server rejects submission if current authoritative pricing differs." } } }, "RetryGenerationRequest": { "type": "object", "required": [ "confirmed", "expected_credits" ], "properties": { "confirmed": { "type": "boolean", "const": true, "description": "Must be true only after the user explicitly approves a new potentially billable attempt." }, "expected_credits": { "type": "integer", "minimum": 0, "description": "Exact credits from the original confirmed task summary approved for this retry. The server rejects the retry if current authoritative pricing differs." } }, "additionalProperties": false }, "Task": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "image_generation_task" }, "service_name": { "type": "string", "const": "源景 AI" }, "engine_name": { "type": "string", "const": "源景图像生成引擎" }, "router_name": { "type": "string", "const": "源景智能路由" }, "capability_id": { "type": "string", "const": "image.free-generation" }, "capability_name": { "type": "string", "const": "自由生图" }, "client_request_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "reconciliation_required", "partial_completed", "completed", "failed", "refunded" ] }, "planned_model": { "type": "string", "description": "Model requested and shown at preview time; this is not proof of the model that actually executed." }, "effective_model": { "type": [ "string", "null" ], "description": "Model proven by execution evidence. Null until that evidence is available; never substitute planned_model." }, "effective_model_status": { "type": "string", "enum": [ "pending_execution_evidence", "not_reported_by_execution_evidence", "verified" ] }, "aspect_ratio": { "type": "string" }, "image_size": { "type": "string" }, "requested_count": { "type": "integer" }, "delivered_count": { "type": "integer" }, "charged_credits": { "type": "integer" }, "refunded_credits": { "type": "integer" }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "Capability": { "type": "object", "required": [ "capability_id", "name", "category", "planning_status", "standalone_generation_status", "workflow_execution_status", "execution_status", "input_schema", "output_schema" ], "properties": { "capability_id": { "type": "string" }, "object": { "type": "string", "const": "capability" }, "name": { "type": "string" }, "category": { "type": "string" }, "capability_type": { "type": "string", "enum": [ "atomic", "composite", "workflow" ] }, "planning_status": { "type": "string", "enum": [ "available" ], "description": "Whether this contract can be selected and planned without executing or charging." }, "standalone_generation_status": { "type": "string", "enum": [ "available", "disabled", "not_applicable" ], "description": "Readiness of the separate POST /api/v1/images/generations surface. It does not accept workflow assets or designers." }, "workflow_execution_status": { "type": "string", "enum": [ "enabled", "disabled", "contract_only" ], "description": "Fail-closed pre-plan snapshot of quote/submit/worker/query/result/download readiness. Enabled requires all runtime flags and a fresh fully capable worker heartbeat; atomic submit rechecks freshness." }, "workflow_execution_reason": { "type": "string", "enum": [ "enabled", "default_off_or_incomplete_runtime", "fresh_worker_readiness_unavailable" ], "description": "Safe public reason for workflow status; omitted while a capability remains contract-only." }, "execution_status": { "type": "string", "enum": [ "available", "contract_only" ], "deprecated": true, "description": "Deprecated compatibility projection of workflow_execution_status. Use the three explicit status fields." }, "description": { "type": "string" }, "input_schema": { "type": "object", "additionalProperties": true }, "output_schema": { "type": "object", "additionalProperties": true }, "supported_models": { "type": "array", "items": { "type": "string" } }, "form": { "type": "object", "additionalProperties": true } } }, "Designer": { "type": "object", "required": [ "id", "object", "name", "is_default" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "designer" }, "name": { "type": "string" }, "description": { "type": "string" }, "style_tags": { "type": "array", "items": { "type": "string" } }, "suitable_tasks": { "type": "array", "items": { "type": "string" } }, "suitable_categories": { "type": "array", "items": { "type": "string" } }, "unsuitable_scenes": { "type": "array", "items": { "type": "string" } }, "is_default": { "type": "boolean" } }, "description": "Safe public summary. Private prompts and workflow instructions are never returned." }, "DesignerWriteRequest": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "designer_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{2,95}$", "description": "Optional on create; generated by the packaged CLI when omitted." }, "name": { "type": "string", "maxLength": 60 }, "description": { "type": "string", "maxLength": 240 }, "identity_description": { "type": "string", "maxLength": 1200 }, "core_approach": { "type": "string", "maxLength": 1200 }, "advanced_preference": { "type": "string", "maxLength": 1200 }, "quote": { "type": "string", "maxLength": 240 }, "style_tags": { "type": "array", "maxItems": 6, "items": { "type": "string", "maxLength": 60 } }, "suitable_tasks": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 80 } }, "suitable_categories": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 80 } }, "unsuitable_scenes": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 120 } }, "set_default": { "type": "boolean", "default": false } }, "description": "User-approved designer profile draft. Creating or updating does not generate media or charge credits." }, "DesignerMutationResponse": { "type": "object", "required": [ "ok", "designer" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean" }, "designer": { "$ref": "#/components/schemas/Designer" } } }, "CustomSkill": { "type": "object", "required": [ "id", "object", "execution_capability_id", "version", "name", "input_roles", "delivery", "outputs" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "custom_skill" }, "execution_capability_id": { "type": "string", "const": "image.free-generation" }, "version": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "input_roles": { "type": "array", "items": { "type": "object", "required": [ "role", "label", "min_count", "max_count" ], "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "product", "reference" ] }, "label": { "type": "string" }, "min_count": { "type": "integer", "minimum": 0, "maximum": 5 }, "max_count": { "type": "integer", "minimum": 0, "maximum": 5 } } } }, "delivery": { "type": "object", "required": [ "model", "aspect_ratio", "image_size", "output_count" ], "additionalProperties": false, "properties": { "model": { "type": "string" }, "aspect_ratio": { "type": "string" }, "image_size": { "type": "string" }, "output_count": { "type": "integer", "minimum": 1, "maximum": 10 } } }, "outputs": { "type": "array", "items": { "type": "object", "required": [ "node_id", "name" ], "additionalProperties": false, "properties": { "node_id": { "type": "string" }, "name": { "type": "string" } } } }, "updated_at": { "type": "string", "format": "date-time" } }, "description": "Owner-scoped safe skill-canvas summary. Node prompts and private designer instructions are never returned." }, "JobPlanRequest": { "type": "object", "required": [ "instruction" ], "additionalProperties": false, "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 4000 }, "capability_id": { "type": "string", "description": "Optional explicit capability from GET /api/v1/capabilities." }, "designer_id": { "type": "string", "description": "Optional owned designer. The key also needs designers:read." }, "asset_ids": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "pattern": "^asset_[A-Za-z0-9_-]+$" } }, "inputs": { "type": "object", "additionalProperties": true, "description": "Capability-specific values. Use the selected capability input_schema as the authoritative contract." }, "preferences": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "auto", "fixed" ] }, "model_mode": { "type": "string", "enum": [ "auto", "fixed" ] }, "preference": { "type": "string", "enum": [ "economy", "balanced", "quality", "fast" ] }, "model": { "type": "string", "enum": [ "gpt-image-2.0", "gpt-image-2-vip", "nano-banana-2", "nano-banana-pro" ] } } } } }, "FormField": { "type": "object", "required": [ "field", "required", "question", "accepts" ], "additionalProperties": false, "properties": { "field": { "type": "string", "description": "Stable dot-path merged into plan inputs." }, "required": { "type": "boolean" }, "question": { "type": "string", "description": "User-facing clarification question." }, "accepts": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "options": { "type": "array", "items": {} }, "default": {}, "section": { "type": "string" }, "depends_on": { "type": "object", "additionalProperties": true } } }, "CommerceOutputResponsibility": { "type": "object", "required": [ "responsibility_version", "sequence", "slot_key", "artifact_role", "index", "code", "label", "purpose", "variant", "filename_stem" ], "additionalProperties": false, "properties": { "responsibility_version": { "type": "string", "const": "commerce_slot_responsibilities_v1" }, "sequence": { "type": "integer", "minimum": 1 }, "slot_key": { "type": "string" }, "artifact_role": { "type": "string" }, "index": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "label": { "type": "string" }, "purpose": { "type": "string" }, "variant": { "type": "integer", "minimum": 1 }, "selling_point_index": { "type": [ "integer", "null" ], "minimum": 1 }, "selling_point": { "type": [ "string", "null" ] }, "filename_stem": { "type": "string" } }, "description": "Safe public per-image job identity. It contains no private prompt or provider metadata." }, "JobPlanResponse": { "type": "object", "required": [ "plan_id", "status", "capability_id", "missing_fields", "proposed_outputs", "model_policy", "estimated_credits", "execution" ], "properties": { "ok": { "type": "boolean", "const": true }, "plan_id": { "type": "string" }, "status": { "type": "string", "enum": [ "needs_input", "ready_for_quote", "expired", "converted_to_job" ] }, "version": { "type": "integer", "minimum": 1 }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "converted_job_id": { "type": [ "string", "null" ] }, "capability_id": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "selection_reason": { "type": "string" }, "image_recipe": { "type": "object", "description": "Public recipe identity only. The server-side compiled prompt is never returned.", "additionalProperties": false, "properties": { "recipe_id": { "type": "string" }, "recipe_version": { "type": "integer", "minimum": 1 }, "display_name": { "type": "string" }, "execution_status": { "type": "string", "enum": [ "available", "disabled", "planned" ] } } }, "resolved_inputs": { "type": "object", "additionalProperties": true }, "form_version": { "type": "string", "default": "yuanjing-form-v1" }, "missing_fields": { "type": "array", "items": { "$ref": "#/components/schemas/FormField" } }, "proposed_outputs": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "proposed_output_slots": { "type": "array", "description": "Present for commerce and platform plans. Order is the intended delivery order.", "items": { "$ref": "#/components/schemas/CommerceOutputResponsibility" } }, "model_policy": { "type": "object", "additionalProperties": true }, "estimated_credits": { "type": "integer", "minimum": 0 }, "estimate": { "type": "object", "additionalProperties": true }, "execution": { "type": "object", "required": [ "started", "billable", "credits_charged", "no_charge_guarantee" ], "properties": { "started": { "type": "boolean", "const": false }, "billable": { "type": "boolean", "const": false }, "credits_charged": { "type": "integer", "const": 0 }, "no_charge_guarantee": { "type": "boolean", "const": true } } } } }, "PlanInputPatch": { "type": "object", "required": [ "expected_version", "inputs" ], "additionalProperties": false, "properties": { "expected_version": { "type": "integer", "minimum": 1 }, "inputs": { "type": "object", "minProperties": 1, "additionalProperties": true } } }, "Asset": { "type": "object", "required": [ "id", "object", "type", "source", "role", "filename", "content_type", "size", "status", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^asset_[A-Za-z0-9_-]+$" }, "object": { "type": "string", "const": "asset" }, "type": { "type": "string", "const": "image" }, "source": { "type": "string", "enum": [ "completed_site_upload", "developer_direct_upload", "developer_r2_temporary_upload" ] }, "role": { "type": "string", "enum": [ "product", "white_bg", "subject", "competitor", "reference", "style", "mixed_reference", "model_reference", "brand" ] }, "filename": { "type": "string" }, "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp" ] }, "size": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "ready", "deleted" ] }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "AssetRegistrationRequest": { "type": "object", "required": [ "upload_key" ], "additionalProperties": false, "properties": { "upload_key": { "type": "string", "description": "Key of an image already uploaded and completed through the authenticated site's upload flow. This endpoint does not upload bytes." }, "role": { "type": "string", "enum": [ "product", "white_bg", "subject", "competitor", "reference", "style", "mixed_reference", "model_reference", "brand" ] } } }, "TemporaryAssetUploadInitRequest": { "type": "object", "required": [ "filename", "content_type", "size", "sha256", "client_request_id" ], "additionalProperties": false, "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 180, "description": "A basename only. Its .jpg/.jpeg, .png, or .webp extension must match content_type." }, "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp" ] }, "size": { "type": "integer", "minimum": 1, "maximum": 20971520, "description": "Exact byte length. The runtime maximum is configurable and may be lower." }, "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$", "description": "SHA-256 hex digest of the exact bytes that will be uploaded." }, "role": { "type": "string", "default": "product", "enum": [ "product", "white_bg", "subject", "competitor", "reference", "style", "mixed_reference", "model_reference", "brand" ] }, "client_request_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Required idempotency key. Reuse only for an identical file contract." } } }, "TemporaryAssetUploadOperationRequest": { "type": "object", "required": [ "upload_id" ], "additionalProperties": false, "properties": { "upload_id": { "type": "string", "pattern": "^aupl_[a-f0-9]{32}$" } } }, "TemporaryAssetUpload": { "type": "object", "required": [ "upload_id", "status", "filename", "content_type", "size", "sha256", "role", "expires_at", "storage", "retention" ], "properties": { "upload_id": { "type": "string", "pattern": "^aupl_[a-f0-9]{32}$" }, "status": { "type": "string", "enum": [ "pending", "completed", "expired", "aborted" ] }, "filename": { "type": "string" }, "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp" ] }, "size": { "type": "integer", "minimum": 1 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "role": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "storage": { "type": "string", "const": "private_r2_temporary" }, "retention": { "type": "string", "const": "temporary" }, "upload_url": { "type": "string", "format": "uri", "description": "Short-lived presigned PUT URL returned only while upload is pending. It is not a permanent public URL." }, "method": { "type": "string", "const": "PUT" }, "required_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Send these exact signed headers with the PUT, including checksum and metadata headers." }, "hash_verification": { "type": "string", "const": "streamed_sha256", "description": "Present after complete has streamed and hashed the stored bytes." }, "idempotent_replay": { "type": "boolean" } }, "description": "Owner-scoped private temporary upload state. The object key, bucket, endpoint, internal user ID, and permanent public URL are never returned." }, "WorkflowQuote": { "type": "object", "required": [ "id", "object", "job_id", "client_request_id", "status", "version", "amount", "job_version", "job_snapshot_fingerprint", "authoritative", "authoritative_scope", "recovery_policy", "max_authorized_credits", "submission_status", "reservation_status", "credits_reserved", "execution_allowed", "expires_at" ], "properties": { "id": { "type": "string", "pattern": "^wquote_" }, "object": { "type": "string", "const": "workflow_quote" }, "job_id": { "type": "string" }, "client_request_id": { "type": "string", "maxLength": 128 }, "status": { "type": "string", "enum": [ "active", "expired", "superseded", "submitted" ] }, "version": { "type": "integer", "minimum": 1 }, "amount": { "type": "object", "required": [ "credits", "currency" ], "properties": { "credits": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "const": "credits" } } }, "recovery_policy": { "$ref": "#/components/schemas/WorkflowAutomaticRecoveryPolicy" }, "max_authorized_credits": { "type": "integer", "minimum": 0, "description": "Maximum credits authorized by this quote. The bounded same-Job recovery adds zero credits." }, "output_count": { "type": "integer", "minimum": 1, "maximum": 100 }, "authoritative": { "type": "boolean", "const": true }, "job_version": { "type": "integer", "minimum": 1 }, "job_snapshot_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "authoritative_scope": { "type": "string", "const": "price_and_job_snapshot_until_expiry" }, "pricing_basis": { "type": "string", "const": "versioned_job_snapshot_v1" }, "price_locked_until": { "type": "string", "format": "date-time" }, "submission_status": { "type": "string", "enum": [ "not_submitted", "submitted" ] }, "reservation_status": { "type": "string", "enum": [ "not_reserved", "reserved", "settled", "refunded" ] }, "reservation_id": { "type": [ "string", "null" ] }, "credits_reserved": { "type": "integer", "minimum": 0 }, "execution_allowed": { "type": "boolean" }, "blocking_reason": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkflowAutomaticRecoveryPolicy": { "type": "object", "required": [ "mode", "automatic", "max_attempts", "added_credits", "preserves_succeeded_outputs", "excludes_reconciliation_pending" ], "properties": { "mode": { "type": "string", "const": "same_job_failed_slots_only" }, "automatic": { "type": "boolean", "const": true }, "max_attempts": { "type": "integer", "const": 1 }, "added_credits": { "type": "integer", "const": 0 }, "requires_open_reservation": { "type": "boolean" }, "preserves_succeeded_outputs": { "type": "boolean", "const": true }, "excludes_reconciliation_pending": { "type": "boolean", "const": true } } }, "WorkflowRecoveryPlan": { "type": "object", "required": [ "id", "object", "client_request_id", "job_id", "strategy", "status", "retry_slot_ids", "manual_action_slot_ids", "inflight_slot_ids", "preserved_slot_ids", "automatic_attempts", "retry_mode", "engine_calls", "execution_started", "credits_charged", "recovery_policy" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "workflow_recovery_plan" }, "client_request_id": { "type": "string" }, "job_id": { "type": "string" }, "strategy": { "type": "string", "const": "missing_slots_only" }, "status": { "type": "string", "enum": [ "wait_for_inflight", "manual_action_required", "manual_retry_available", "nothing_to_recover" ] }, "retry_slot_ids": { "type": "array", "items": { "type": "string" } }, "manual_action_slot_ids": { "type": "array", "items": { "type": "string" } }, "inflight_slot_ids": { "type": "array", "items": { "type": "string" } }, "preserved_slot_ids": { "type": "array", "items": { "type": "string" } }, "automatic_attempts": { "type": "integer", "const": 1 }, "retry_mode": { "type": "string", "const": "automatic_once_then_operator_fallback" }, "engine_calls": { "type": "integer", "const": 0 }, "execution_started": { "type": "boolean", "const": false }, "credits_charged": { "type": "integer", "const": 0 }, "recovery_policy": { "$ref": "#/components/schemas/WorkflowAutomaticRecoveryPolicy" }, "created_at": { "type": "string", "format": "date-time" } } }, "WorkflowManualHandoff": { "type": "object", "required": [ "id", "client_request_id", "reason", "status", "created_at" ], "properties": { "id": { "type": "string" }, "client_request_id": { "type": "string" }, "reason": { "type": "string", "enum": [ "non_retryable_failure", "retry_exhausted", "user_requested", "operator_review" ] }, "status": { "type": "string", "const": "requested" }, "created_at": { "type": "string", "format": "date-time" } } }, "WorkflowJob": { "type": "object", "required": [ "id", "object", "client_request_id", "plan_id", "capability_id", "status", "proposed_outputs", "output_count", "execution_started", "credits_charged", "recovery_policy" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "workflow_job" }, "client_request_id": { "type": "string" }, "plan_id": { "type": "string" }, "capability_id": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "awaiting_confirmation", "confirmed", "queued", "running", "partially_succeeded", "succeeded", "failed", "manual_action_required", "canceled" ] }, "confirmation_status": { "type": "string", "enum": [ "pending", "confirmed" ] }, "proposed_outputs": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "output_count": { "type": "integer", "minimum": 1 }, "estimated_credits": { "type": "integer", "minimum": 0 }, "execution_started": { "type": "boolean" }, "credits_charged": { "type": "integer", "const": 0 }, "recovery_policy": { "$ref": "#/components/schemas/WorkflowAutomaticRecoveryPolicy" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WorkflowOutputSlot": { "type": "object", "properties": { "id": { "type": "string" }, "job_id": { "type": "string" }, "type": { "type": "string" }, "index": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "planned", "queued", "running", "succeeded", "failed", "manual_action_required", "canceled" ] }, "selected_attempt_id": { "type": [ "string", "null" ] }, "responsibility": { "anyOf": [ { "$ref": "#/components/schemas/CommerceOutputResponsibility" }, { "type": "null" } ] }, "attempts": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "WorkflowSubmitRequest": { "type": "object", "required": [ "quote_id", "quote_version", "job_version", "expected_credits" ], "additionalProperties": false, "properties": { "confirmed": { "type": "boolean", "description": "Set true after explicit approval. When omitted/false, approval_policy_id must cover this exact quote/job binding." }, "approval_policy_id": { "type": "string", "pattern": "^apol_", "description": "Default-off bounded authorization. It never authorizes retry, refund, payment or balance adjustment." }, "quote_id": { "type": "string", "pattern": "^wquote_[A-Za-z0-9-]{1,128}$" }, "quote_version": { "type": "integer", "minimum": 1 }, "job_version": { "type": "integer", "minimum": 1 }, "expected_credits": { "type": "integer", "minimum": 0 } } }, "WorkflowCreditReservation": { "type": "object", "required": [ "id", "object", "job_id", "quote_id", "credits", "currency", "status" ], "properties": { "id": { "type": "string", "pattern": "^wreserve_" }, "object": { "type": "string", "const": "workflow_credit_reservation" }, "job_id": { "type": "string" }, "quote_id": { "type": "string" }, "credits": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "const": "credits" }, "status": { "type": "string", "enum": [ "reserved", "settled", "refunded" ] }, "settled_credits": { "type": [ "integer", "null" ], "minimum": 0 }, "refunded_credits": { "type": [ "integer", "null" ], "minimum": 0 }, "finalized_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WorkflowArtifact": { "type": "object", "required": [ "id", "object", "job_id", "slot_id", "artifact_type", "sha256", "media_type", "byte_size" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "workflow_artifact" }, "job_id": { "type": "string" }, "slot_id": { "type": "string" }, "attempt_id": { "type": "string" }, "artifact_type": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "media_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp" ] }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "byte_size": { "type": "integer", "minimum": 1 }, "planned_model": { "type": [ "string", "null" ] }, "effective_model": { "type": [ "string", "null" ] }, "effective_model_status": { "type": "string" }, "download_status": { "type": "string" }, "result_ref": { "type": "string", "pattern": "^artifact:" } }, "description": "Owner-bound immutable evidence. Private generation-node URLs, storage locators and signed URLs are never returned." }, "WorkflowDownloadGrant": { "type": "object", "required": [ "object", "download_url", "expires_at" ], "properties": { "object": { "type": "string", "enum": [ "workflow_artifact_download", "workflow_artifact_package" ] }, "download_url": { "type": "string", "pattern": "^/api/v1/workflow-downloads/[A-Za-z0-9_-]{43}$" }, "expires_at": { "type": "string", "format": "date-time" }, "artifact_id": { "type": "string" }, "artifact_count": { "type": "integer", "minimum": 1 } } }, "Model": { "type": "object", "required": [ "id", "object", "name", "credits_per_image" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "object": { "const": "model" }, "name": { "type": "string" }, "credits_per_image": { "type": "integer", "minimum": 0 } } }, "ModelListResponse": { "type": "object", "required": [ "object", "data" ], "additionalProperties": false, "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "BalanceResponse": { "type": "object", "required": [ "ok", "balance", "currency" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "balance": { "type": "number", "minimum": 0 }, "currency": { "const": "credits" } } }, "UsageItem": { "type": "object", "required": [ "requestId", "method", "path", "status", "createdAt" ], "additionalProperties": false, "properties": { "requestId": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "requestedCount": { "type": [ "integer", "null" ] }, "deliveredCount": { "type": "integer", "minimum": 0 }, "status": { "type": "string" }, "errorCode": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "integer", "null" ], "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" } } }, "UsageResponse": { "type": "object", "required": [ "ok", "api_key_id", "items", "requests", "requestsToday", "generatedImages" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "api_key_id": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/UsageItem" } }, "requests": { "type": "integer", "minimum": 0 }, "requestsToday": { "type": "integer", "minimum": 0 }, "generatedImages": { "type": "integer", "minimum": 0 } } }, "AssetRegistrationResponse": { "type": "object", "required": [ "ok", "operation", "upload_performed", "asset", "idempotent_replay" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "operation": { "const": "register_completed_upload" }, "upload_performed": { "const": false }, "asset": { "$ref": "#/components/schemas/Asset" }, "idempotent_replay": { "type": "boolean" } } }, "AssetDeleteResponse": { "type": "object", "required": [ "ok", "asset" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "asset": { "$ref": "#/components/schemas/Asset" } } }, "AssetUploadResponse": { "type": "object", "required": [ "ok", "operation", "upload_performed", "generation_started", "credits_charged", "asset", "idempotent_replay" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "operation": { "const": "upload_and_register_asset" }, "upload_performed": { "type": "boolean" }, "generation_started": { "const": false }, "credits_charged": { "const": 0 }, "asset": { "$ref": "#/components/schemas/Asset" }, "idempotent_replay": { "type": "boolean" } } }, "TemporaryAssetUploadInitResponse": { "type": "object", "required": [ "ok", "upload" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "upload": { "$ref": "#/components/schemas/TemporaryAssetUpload" } } }, "WorkflowJobResponse": { "type": "object", "required": [ "ok", "idempotent_replay", "job" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "idempotent_replay": { "type": "boolean" }, "job": { "$ref": "#/components/schemas/WorkflowJob" } } }, "WorkflowJobListResponse": { "type": "object", "required": [ "object", "data", "count" ], "additionalProperties": false, "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowJob" } }, "count": { "type": "integer", "minimum": 0 } } }, "WorkflowDownloadCapability": { "type": "object", "required": [ "available" ], "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "method": { "const": "issue_opaque_single_use_token" }, "reason": { "const": "workflow_download_capability_not_configured" } } }, "WorkflowCreditsEvidence": { "type": "object", "required": [ "estimated", "reserved", "charged", "refunded", "actual", "reservation_status", "ledger_evidence_status", "evidenced_output_count" ], "properties": { "estimated": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0 }, "charged": { "type": "integer", "minimum": 0 }, "refunded": { "type": "integer", "minimum": 0 }, "actual": { "type": [ "integer", "null" ], "minimum": 0 }, "reservation_status": { "type": "string" }, "ledger_evidence_status": { "type": "string" }, "evidenced_output_count": { "type": "integer", "minimum": 0 } } }, "WorkflowResultReference": { "type": "object", "required": [ "id", "object", "result_ref", "job_id", "slot_id", "artifact_type", "media_type", "byte_size", "download" ], "properties": { "id": { "type": "string" }, "object": { "const": "workflow_result_reference" }, "result_ref": { "type": "string", "pattern": "^artifact:" }, "job_id": { "type": "string" }, "slot_id": { "type": "string" }, "attempt_id": { "type": "string" }, "artifact_type": { "type": "string" }, "media_type": { "type": "string" }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "byte_size": { "type": "integer", "minimum": 1 }, "download": { "$ref": "#/components/schemas/WorkflowDownloadCapability" } } }, "WorkflowResult": { "type": "object", "required": [ "result_id", "object", "job_id", "manifest_id", "capability_id", "status", "completion_status", "requested_count", "delivered_count", "artifact_count", "planned_model", "effective_model", "effective_models", "effective_model_status", "credits", "artifacts", "download" ], "properties": { "result_id": { "type": "string" }, "object": { "const": "workflow_result" }, "job_id": { "type": "string" }, "manifest_id": { "type": "string" }, "capability_id": { "type": "string" }, "status": { "type": "string" }, "completion_status": { "type": "string", "enum": [ "pending", "partial", "complete", "none" ] }, "requested_count": { "type": "integer", "minimum": 0 }, "delivered_count": { "type": "integer", "minimum": 0 }, "artifact_count": { "type": "integer", "minimum": 0 }, "planned_model": { "type": [ "string", "null" ] }, "effective_model": { "type": [ "string", "null" ] }, "effective_models": { "type": "array", "items": { "type": "string" } }, "effective_model_status": { "type": "string", "enum": [ "recorded_by_execution_evidence", "mixed_execution_evidence", "not_fully_reported_by_execution_evidence", "not_reported_by_execution_evidence" ] }, "credits": { "$ref": "#/components/schemas/WorkflowCreditsEvidence" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowResultReference" } }, "download": { "$ref": "#/components/schemas/WorkflowDownloadCapability" } } }, "WorkflowManifestOutput": { "type": "object", "required": [ "slot_id", "artifact_type", "index", "status", "effective_model_status", "billing_evidence_status", "result_refs" ], "properties": { "slot_id": { "type": "string" }, "artifact_type": { "type": "string" }, "index": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "planned_model": { "type": [ "string", "null" ] }, "effective_model": { "type": [ "string", "null" ] }, "effective_model_status": { "type": "string" }, "billing_evidence_status": { "type": "string" }, "responsibility": { "anyOf": [ { "$ref": "#/components/schemas/CommerceOutputResponsibility" }, { "type": "null" } ] }, "result_refs": { "type": "array", "items": { "type": "object", "required": [ "id", "result_ref", "media_type", "byte_size", "download" ], "properties": { "id": { "type": "string" }, "result_ref": { "type": "string", "pattern": "^artifact:" }, "media_type": { "type": "string" }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "byte_size": { "type": "integer", "minimum": 1 }, "download": { "$ref": "#/components/schemas/WorkflowDownloadCapability" } } } } } }, "WorkflowResultManifest": { "type": "object", "required": [ "manifest_id", "object", "job_id", "capability_id", "status", "completion_status", "requested_count", "delivered_count", "artifact_count", "planned_model", "effective_model", "effective_models", "effective_model_status", "credits", "outputs", "download" ], "properties": { "manifest_id": { "type": "string" }, "object": { "const": "workflow_result_manifest" }, "job_id": { "type": "string" }, "capability_id": { "type": "string" }, "status": { "type": "string" }, "completion_status": { "type": "string", "enum": [ "pending", "partial", "complete", "none" ] }, "requested_count": { "type": "integer", "minimum": 0 }, "delivered_count": { "type": "integer", "minimum": 0 }, "artifact_count": { "type": "integer", "minimum": 0 }, "planned_model": { "type": [ "string", "null" ] }, "effective_model": { "type": [ "string", "null" ] }, "effective_models": { "type": "array", "items": { "type": "string" } }, "effective_model_status": { "type": "string", "enum": [ "recorded_by_execution_evidence", "mixed_execution_evidence", "not_fully_reported_by_execution_evidence", "not_reported_by_execution_evidence" ] }, "credits": { "$ref": "#/components/schemas/WorkflowCreditsEvidence" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowManifestOutput" } }, "download": { "$ref": "#/components/schemas/WorkflowDownloadCapability" } } }, "WorkflowSubmitResponse": { "type": "object", "required": [ "ok", "idempotent_replay", "reservation", "job", "execution_started", "dispatch_queued", "credits_reserved" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "idempotent_replay": { "type": "boolean" }, "reservation": { "$ref": "#/components/schemas/WorkflowCreditReservation" }, "job": { "$ref": "#/components/schemas/WorkflowJob" }, "execution_started": { "type": "boolean" }, "dispatch_queued": { "type": "boolean" }, "credits_reserved": { "type": "integer", "minimum": 0 } } }, "WorkflowQuoteResponse": { "type": "object", "required": [ "ok", "idempotent_replay", "quote" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "idempotent_replay": { "type": "boolean" }, "quote": { "$ref": "#/components/schemas/WorkflowQuote" } } }, "WorkflowRecoveryPlanResponse": { "type": "object", "required": [ "ok", "idempotent_replay", "orchestration_contract_only", "engine_calls", "execution_started", "credits_charged", "recovery_plan" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "idempotent_replay": { "type": "boolean" }, "orchestration_contract_only": { "const": true }, "engine_calls": { "const": 0 }, "execution_started": { "const": false }, "credits_charged": { "const": 0 }, "recovery_plan": { "$ref": "#/components/schemas/WorkflowRecoveryPlan" } } }, "WorkflowManualHandoffResponse": { "type": "object", "required": [ "ok", "idempotent_replay", "orchestration_contract_only", "engine_calls", "execution_started", "credits_charged", "handoff", "job" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "idempotent_replay": { "type": "boolean" }, "orchestration_contract_only": { "const": true }, "engine_calls": { "const": 0 }, "execution_started": { "const": false }, "credits_charged": { "const": 0 }, "handoff": { "$ref": "#/components/schemas/WorkflowManualHandoff" }, "job": { "$ref": "#/components/schemas/WorkflowJob" } } }, "WorkflowSlotRetryResponse": { "type": "object", "required": [ "ok", "idempotent_replay", "credits_reserved", "retry_slot_ids", "job" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "idempotent_replay": { "type": "boolean" }, "credits_reserved": { "type": "integer", "const": 0 }, "retry_slot_ids": { "type": "array", "items": { "type": "string" } }, "job": { "$ref": "#/components/schemas/WorkflowJob" } } }, "GenerationSubmissionResponse": { "type": "object", "required": [ "ok", "task_id", "client_request_id", "status", "idempotent_replay", "service_name", "engine_name", "router_name", "capability_id", "capability_name", "planned_model", "aspect_ratio", "image_size", "requested_count", "estimated_credits", "effective_model", "effective_model_status" ], "properties": { "ok": { "const": true }, "task_id": { "type": "string" }, "client_request_id": { "type": "string" }, "status": { "type": "string" }, "idempotent_replay": { "type": "boolean" }, "service_name": { "const": "源景 AI" }, "engine_name": { "const": "源景图像生成引擎" }, "router_name": { "const": "源景智能路由" }, "capability_id": { "const": "image.free-generation" }, "capability_name": { "const": "自由生图" }, "planned_model": { "type": "string" }, "aspect_ratio": { "type": "string" }, "image_size": { "type": "string" }, "requested_count": { "type": "integer", "minimum": 1, "maximum": 4 }, "estimated_credits": { "type": [ "integer", "null" ], "minimum": 0 }, "effective_model": { "type": "null" }, "effective_model_status": { "const": "pending_execution_evidence" } } }, "GenerationRetryResponse": { "allOf": [ { "$ref": "#/components/schemas/GenerationSubmissionResponse" }, { "type": "object", "required": [ "retry_of" ], "properties": { "retry_of": { "type": "string" } } } ] }, "TaskListResponse": { "type": "object", "required": [ "ok", "tasks" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } }, "TaskResponse": { "type": "object", "required": [ "ok", "task" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "task": { "$ref": "#/components/schemas/Task" } } }, "WorkflowArtifactResponse": { "type": "object", "required": [ "ok", "artifact", "download" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "artifact": { "$ref": "#/components/schemas/WorkflowArtifact" }, "download": { "$ref": "#/components/schemas/WorkflowDownloadCapability" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "ErrorBody": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "AgentApprovalPolicyIntent": { "type": "object", "required": [ "id", "status", "connection_id", "expires_at" ], "properties": { "id": { "type": "string", "pattern": "^apint_" }, "status": { "type": "string", "enum": [ "pending", "approved", "expired", "canceled" ] }, "connection_id": { "type": "string" }, "policy_id": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "requested_policy": { "type": "object", "description": "Account-visible capability, credit, output, timezone and validity bounds.", "additionalProperties": true }, "approval_path": { "type": "string", "description": "Logged-in browser confirmation path. The Agent cannot activate its own intent." } } }, "AgentApprovalPolicy": { "type": "object", "required": [ "id", "connection_id", "status", "capabilities", "max_credits_per_job", "daily_credit_limit", "total_credit_limit", "max_outputs_per_job", "total_output_limit", "timezone", "valid_from", "expires_at" ], "properties": { "id": { "type": "string", "pattern": "^apol_" }, "connection_id": { "type": "string", "pattern": "^acon_" }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "capabilities": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "max_credits_per_job": { "type": "integer", "minimum": 0 }, "daily_credit_limit": { "type": "integer", "minimum": 0 }, "total_credit_limit": { "type": "integer", "minimum": 0 }, "max_outputs_per_job": { "type": "integer", "minimum": 1 }, "total_output_limit": { "type": "integer", "minimum": 1 }, "timezone": { "type": "string", "example": "Asia/Shanghai" }, "valid_from": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "usage": { "type": "object", "properties": { "day_key": { "type": "string" }, "daily_reserved_credits": { "type": "integer", "minimum": 0 }, "total_reserved_credits": { "type": "integer", "minimum": 0 }, "total_reserved_outputs": { "type": "integer", "minimum": 0 } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } }, "description": "Default-off, user-created authorization bound to one active Agent connection. Reservations are monotonic: ambiguous network outcomes do not release capacity." }, "AgentSkillManifest": { "type": "object", "required": [ "schema_version", "skill_name", "current_version", "package_url", "sha256", "authorization_mode" ], "properties": { "schema_version": { "type": "string", "example": "1.0" }, "skill_name": { "type": "string", "example": "yuanjing-ai" }, "current_version": { "type": "string" }, "protocol_version": { "type": "string" }, "package_url": { "type": "string", "format": "uri" }, "claude_package_url": { "type": "string", "format": "uri" }, "sha256": { "type": "string" }, "supported_clients": { "type": "array", "items": { "type": "string" } }, "bootstrap": { "type": "object", "additionalProperties": true }, "api_base_url": { "type": "string", "format": "uri" }, "openapi_url": { "type": "string", "format": "uri" }, "install_modes": { "type": "array", "items": { "type": "string" } }, "authorization_mode": { "type": "string", "example": "device_code_pkce" }, "security_notice": { "type": "string" } } }, "DeviceStartRequest": { "type": "object", "required": [ "code_challenge", "code_challenge_method" ], "additionalProperties": false, "properties": { "code_challenge": { "type": "string", "minLength": 43, "maxLength": 128 }, "code_challenge_method": { "type": "string", "enum": [ "S256" ] }, "client_type": { "type": "string", "enum": [ "cursor", "codex", "claude", "generic" ] }, "client_name": { "type": "string", "maxLength": 80 } } }, "DeviceStartResponse": { "type": "object", "properties": { "device_code": { "type": "string" }, "user_code": { "type": "string", "example": "ABCD-EFGH" }, "verification_uri": { "type": "string", "format": "uri" }, "verification_uri_complete": { "type": "string", "format": "uri" }, "expires_in": { "type": "integer" }, "interval": { "type": "integer" } } }, "DeviceTokenRequest": { "type": "object", "required": [ "device_code", "code_verifier" ], "additionalProperties": false, "properties": { "device_code": { "type": "string" }, "code_verifier": { "type": "string", "minLength": 43, "maxLength": 128 } } }, "DeviceTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "description": "完整 Developer Key，仅此响应返回一次" }, "token_type": { "type": "string", "example": "Bearer" }, "scope": { "type": "string" }, "connection": { "$ref": "#/components/schemas/AgentConnection" } } }, "AgentConnection": { "type": "object", "properties": { "id": { "type": "string" }, "client_type": { "type": "string" }, "client_name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_activation", "active", "paused", "revoked" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "authorization": { "type": "object", "properties": { "mode": { "type": "string", "example": "persistent_until_revoked" }, "user_visible_daily_quota": { "type": "boolean", "const": false }, "user_visible_per_request_cap": { "type": "boolean", "const": false }, "expires_in_days": { "type": "integer", "nullable": true, "description": "始终为 null；持续有效直到撤销" } } }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "VisualObservation": { "type": "object", "required": [ "field", "value", "confidence", "evidence_type", "evidence", "source_asset_id" ], "properties": { "field": { "type": "string" }, "value": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "evidence_type": { "type": "string", "enum": [ "vision", "user_text", "metadata" ] }, "evidence": { "type": "string" }, "source_asset_id": { "type": "string" } } }, "JobIntakeRequest": { "type": "object", "required": [ "user_text", "client_request_id" ], "additionalProperties": false, "properties": { "user_text": { "type": "string", "maxLength": 4000 }, "asset_ids": { "type": "array", "items": { "type": "string" } }, "agent_visual_observations": { "type": "array", "items": { "$ref": "#/components/schemas/VisualObservation" } }, "requested_output": { "type": "object", "additionalProperties": true }, "client_request_id": { "type": "string", "maxLength": 128 } } }, "JobIntakeResponse": { "type": "object", "properties": { "inferred_fields": { "type": "object", "additionalProperties": true }, "accepted_fields": { "type": "object", "additionalProperties": true }, "uncertain_fields": { "type": "array", "items": { "type": "object" } }, "missing_fields": { "type": "array", "items": { "type": "object" } }, "risky_claims": { "type": "array", "items": { "type": "object" } }, "selected_capability": { "type": "string" }, "output_scope": { "type": "string" }, "proposed_count": { "type": "integer" }, "plan_summary": { "type": "object", "additionalProperties": true }, "confirmation_card": { "type": "object", "additionalProperties": true } } }, "ResultAuditRequest": { "type": "object", "properties": { "expected_count": { "type": "integer" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "plan_index": { "type": "integer" }, "mime": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "local_path": { "type": "string" }, "sha256": { "type": "string" } } } }, "agent_visual_audit": { "type": "array", "description": "仅作 agent_advisory，不可单独触发免费修复", "items": { "type": "object", "properties": { "field": { "type": "string" }, "judgment": { "type": "string" } } } } } }, "ResultAuditResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "audit_enabled": { "type": "boolean" }, "repair_enabled": { "type": "boolean" }, "next_status": { "type": "string", "enum": [ "audit_passed", "audit_failed_objective", "repair_queued", "partial_success", "delivered" ] }, "slots": { "type": "array", "items": { "type": "object", "properties": { "plan_index": { "type": "integer" }, "status": { "type": "string" }, "authority": { "type": "string", "enum": [ "server_verified", "agent_advisory", "user_subjective" ] }, "findings": { "type": "array", "items": { "type": "object" } } } } }, "advisory": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "judgment": { "type": "string" }, "authority": { "type": "string", "const": "agent_advisory" }, "can_trigger_free_repair": { "type": "boolean", "const": false } } } }, "repair_policy": { "type": "object", "additionalProperties": true } } }, "ShopPanelPromptReverseRequest": { "type": "object", "required": [ "confirmed", "expected_credits" ], "additionalProperties": false, "properties": { "confirmed": { "type": "boolean", "description": "Must be true after user approves expected_credits" }, "expected_credits": { "type": "integer", "minimum": 1, "description": "Authoritative credits the user approved" }, "expectedCredits": { "type": "integer", "minimum": 1 }, "client_request_id": { "type": "string", "minLength": 8, "maxLength": 80 }, "clientRequestId": { "type": "string", "minLength": 8, "maxLength": 80 }, "imageUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 5 }, "images": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 5 }, "imagesBase64": { "type": "array", "items": { "type": "object" }, "maxItems": 5 }, "images_base64": { "type": "array", "items": { "type": "object" }, "maxItems": 5 }, "decompose_goal": { "type": "string", "maxLength": 500 }, "decomposeGoal": { "type": "string", "maxLength": 500 }, "market_country": { "type": "string", "maxLength": 20 }, "marketCountry": { "type": "string", "maxLength": 20 } } }, "ShopPanelBusinessPlaybookRequest": { "type": "object", "required": [ "confirmed", "expected_credits", "title" ], "additionalProperties": false, "properties": { "confirmed": { "type": "boolean", "description": "Must be true after user approves expected_credits" }, "expected_credits": { "type": "integer", "minimum": 1, "description": "Authoritative credits the user approved" }, "expectedCredits": { "type": "integer", "minimum": 1 }, "client_request_id": { "type": "string", "minLength": 8, "maxLength": 80 }, "clientRequestId": { "type": "string", "minLength": 8, "maxLength": 80 }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "imageUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 5 }, "images": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 5 }, "category": { "type": "string", "maxLength": 120 }, "attributes_text": { "type": "string", "maxLength": 4000 }, "attributesText": { "type": "string", "maxLength": 4000 }, "audience_hint": { "type": "string", "maxLength": 200 }, "audienceHint": { "type": "string", "maxLength": 200 }, "market_country": { "type": "string", "maxLength": 20 }, "marketCountry": { "type": "string", "maxLength": 20 } } }, "DeviceApprovalResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "status", "client_name", "client_type", "scopes", "message" ], "properties": { "ok": { "type": "boolean", "const": true }, "status": { "type": "string", "enum": [ "approved" ] }, "client_name": { "type": "string" }, "client_type": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } } }, "AgentConnectionMutationResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "connection" ], "properties": { "ok": { "type": "boolean", "const": true }, "connection": { "$ref": "#/components/schemas/AgentConnection" } } }, "AgentVideoRequest": { "type": "object", "additionalProperties": true, "properties": { "client_request_id": { "type": "string", "minLength": 8, "maxLength": 120, "description": "Stable idempotency key." }, "asset_ids": { "type": "array", "items": { "type": "string" }, "description": "Owner-bound Developer asset IDs." }, "start_asset_id": { "type": "string" }, "end_asset_id": { "type": "string" } } }, "AgentVideoConfirmedRequest": { "allOf": [ { "$ref": "#/components/schemas/AgentVideoRequest" }, { "type": "object", "required": [ "client_request_id", "confirmed", "expected_credits", "quote_fingerprint" ], "properties": { "confirmed": { "const": true }, "expected_credits": { "type": "integer", "minimum": 0 }, "quote_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } ] }, "AgentOneClickStoryboardRequest": { "type": "object", "additionalProperties": true, "properties": { "client_request_id": { "type": "string", "minLength": 8, "maxLength": 120 }, "subject_asset_ids": { "type": "array", "items": { "type": "string" } }, "reference_asset_ids": { "type": "array", "items": { "type": "string" } }, "duration": { "type": "string", "enum": [ "8", "16" ] } } }, "AgentOneClickStoryboardConfirmedRequest": { "allOf": [ { "$ref": "#/components/schemas/AgentOneClickStoryboardRequest" }, { "type": "object", "required": [ "client_request_id", "confirmed", "expected_credits", "quote_fingerprint" ], "properties": { "confirmed": { "const": true }, "expected_credits": { "type": "integer", "minimum": 0 }, "quote_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } ] }, "AgentOneClickRenderRequest": { "type": "object", "additionalProperties": true, "properties": { "client_request_id": { "type": "string", "minLength": 8, "maxLength": 120 }, "sessionId": { "type": "string" }, "duration": { "type": "string" } } }, "AgentOneClickRenderConfirmedRequest": { "allOf": [ { "$ref": "#/components/schemas/AgentOneClickRenderRequest" }, { "type": "object", "required": [ "client_request_id", "confirmed", "expected_credits", "quote_fingerprint" ], "properties": { "confirmed": { "const": true }, "expected_credits": { "type": "integer", "minimum": 0 }, "quote_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } ] }, "AgentVideoQuote": { "type": "object", "additionalProperties": true, "required": [ "ok", "expected_credits", "quote_fingerprint", "charged_credits" ], "properties": { "ok": { "type": "boolean" }, "capability_id": { "type": "string" }, "expected_credits": { "type": "integer", "minimum": 0 }, "quote_fingerprint": { "type": "string" }, "confirmed": { "type": "boolean" }, "charged_credits": { "type": "integer", "const": 0 }, "quote": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/models": { "get": { "summary": "List models", "description": "Required scope: models:read. The Agent CLI uses this read-only endpoint to build generation_preview pricing before any generation POST.\n\n模型展示名：源景 G2 / 源景 G2-PRO / 源景 N2 / 源景 N2-PRO。算力价格以本接口实时返回为准，文档不得硬编码静态价格。", "x-required-scope": "models:read", "responses": { "200": { "description": "Model list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelListResponse" }, "example": { "object": "list", "data": [ { "id": "gpt-image-2.0", "object": "model", "name": "源景 G2", "credits_per_image": 100 } ] } } } } }, "operationId": "listModels", "tags": [ "图片模型", "账户与用量" ] } }, "/api/v1/balance": { "get": { "summary": "Get balance", "description": "Required scope: usage:read.", "x-required-scope": "usage:read", "responses": { "200": { "description": "Credit balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" }, "example": { "ok": true, "balance": 1200, "currency": "credits" } } } } }, "operationId": "getBalance" } }, "/api/v1/usage": { "get": { "summary": "Get usage", "description": "Required scope: usage:read.", "x-required-scope": "usage:read", "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } } }, "operationId": "getUsage" } }, "/api/v1/capabilities": { "get": { "summary": "List public capability contracts", "description": "Required scope: models:read. Inspect planning_status, standalone_generation_status and workflow_execution_status before planning. Workflow enabled requires the common execution flags, Provider-query recovery and a fresh fully capable Worker heartbeat; commerce capabilities additionally require their independent execution gate. Submit rechecks the capability and heartbeat atomically. execution_status is a deprecated workflow-only compatibility projection and must not be used to infer readiness by itself.", "x-required-scope": "models:read", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "execution_status", "in": "query", "deprecated": true, "schema": { "type": "string", "enum": [ "available", "contract_only" ] } }, { "name": "workflow_execution_status", "in": "query", "schema": { "type": "string", "enum": [ "enabled", "disabled", "contract_only" ] } }, { "name": "standalone_generation_status", "in": "query", "schema": { "type": "string", "enum": [ "available", "disabled", "not_applicable" ] } } ], "responses": { "200": { "description": "Capability list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Invalid developer key" }, "403": { "description": "Missing required scope" } }, "operationId": "listCapabilities" } }, "/api/v1/capabilities/{id}": { "get": { "summary": "Get one public capability contract", "description": "Required scope: models:read. Inspect the three explicit runtime status fields before creating a plan or choosing a paid surface.", "x-required-scope": "models:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Capability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capability" } } } }, "404": { "description": "Capability not found" } }, "operationId": "getCapability" } }, "/api/v1/custom-skills": { "get": { "summary": "List the authenticated account's custom skills", "description": "Required scope: custom-skills:read. Returns only safe owner-scoped routing metadata; node prompts and private designer instructions remain server-side.", "x-required-scope": "custom-skills:read", "responses": { "200": { "description": "Custom skill list", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "count" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomSkill" } }, "count": { "type": "integer", "minimum": 0 } } } } } }, "403": { "description": "The developer key lacks custom-skills:read" } }, "operationId": "listCustomSkills" } }, "/api/v1/custom-skills/{skillId}": { "get": { "summary": "Get one owned custom skill", "description": "Required scope: custom-skills:read. Cross-account and missing identifiers both return 404.", "x-required-scope": "custom-skills:read", "parameters": [ { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Custom skill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSkill" } } } }, "404": { "description": "Custom skill not found" } }, "operationId": "getCustomSkill" } }, "/api/v1/designers": { "get": { "summary": "List the authenticated account's designers", "description": "Required scope: designers:read. Results are owner-scoped safe summaries and never include private prompts.", "x-required-scope": "designers:read", "responses": { "200": { "description": "Designer list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Designer" } }, "count": { "type": "integer" }, "default_designer_id": { "type": [ "string", "null" ] } } } } } }, "403": { "description": "The developer key lacks designers:read" } }, "operationId": "listDesigners" }, "post": { "summary": "Create an owned designer from a user-approved profile draft", "description": "Required scopes: designers:read and images:write. This changes account profile data but does not generate media or charge credits. The Agent must first obtain user approval for the exact profile draft and allowed local-file scope.", "x-required-scopes": [ "designers:read", "images:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignerWriteRequest" } } } }, "responses": { "201": { "description": "Designer created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignerMutationResponse" } } } }, "400": { "description": "Invalid or duplicate designer draft" }, "403": { "description": "The developer key lacks designers:read or images:write" } }, "operationId": "createDesigner" } }, "/api/v1/designers/default": { "get": { "summary": "Get the authenticated account's default designer", "description": "Required scope: designers:read.", "x-required-scope": "designers:read", "responses": { "200": { "description": "Default designer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Designer" } } } }, "404": { "description": "No default designer" } }, "operationId": "getDefaultDesigner" }, "put": { "summary": "Set one owned designer as default", "description": "Required scopes: designers:read and images:write. This changes account profile data but does not generate media or charge credits.", "x-required-scopes": [ "designers:read", "images:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "designer_id" ], "additionalProperties": false, "properties": { "designer_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Default designer updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignerMutationResponse" } } } }, "404": { "description": "Designer not found or not owned by the key account" } }, "operationId": "setDefaultDesigner" } }, "/api/v1/designers/{designerId}": { "get": { "summary": "Get one owned designer", "description": "Required scope: designers:read. Cross-account and missing identifiers both return 404.", "x-required-scope": "designers:read", "parameters": [ { "name": "designerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Designer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Designer" } } } }, "404": { "description": "Designer not found or not owned by the key account" } }, "operationId": "getDesigner" }, "put": { "summary": "Update one owned designer from a user-approved profile draft", "description": "Required scopes: designers:read and images:write. Cross-account and missing identifiers return 404. This changes account profile data but does not generate media or charge credits.", "x-required-scopes": [ "designers:read", "images:write" ], "parameters": [ { "name": "designerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignerWriteRequest" } } } }, "responses": { "200": { "description": "Designer updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesignerMutationResponse" } } } }, "400": { "description": "Invalid designer draft" }, "404": { "description": "Designer not found or not owned by the key account" } }, "operationId": "updateDesigner" } }, "/api/v1/assets": { "post": { "summary": "Register a completed site upload as an Agent asset", "description": "Required scope: assets:write. Registers an image that has already completed the authenticated site's upload flow. This is JSON metadata registration, not a multipart or binary upload endpoint. It does not start generation or charge credits.", "x-required-scope": "assets:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRegistrationRequest" } } } }, "responses": { "200": { "description": "Idempotent registration replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRegistrationResponse" } } } }, "201": { "description": "Asset registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRegistrationResponse" } } } }, "404": { "description": "Completed upload not found for this account" }, "409": { "description": "Upload is not completed" } }, "operationId": "registerAsset" }, "get": { "summary": "List owned Agent assets", "description": "Required scope: assets:read.", "x-required-scope": "assets:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Owner-scoped asset list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "count": { "type": "integer" } } } } } } }, "operationId": "listAssets" } }, "/api/v1/assets/{assetId}": { "get": { "summary": "Get one owned Agent asset", "description": "Required scope: assets:read. Cross-account and missing IDs both return 404.", "x-required-scope": "assets:read", "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "404": { "description": "Asset not found" } }, "operationId": "getAsset" }, "delete": { "summary": "Soft-delete one owned Agent asset", "description": "Required scope: assets:write. This hides the asset from future Agent reads; it does not operate on another account's upload.", "x-required-scope": "assets:write", "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Asset marked deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDeleteResponse" } } } }, "404": { "description": "Asset not found" } }, "operationId": "deleteAsset" } }, "/api/v1/assets/upload": { "post": { "summary": "Upload and register one local Agent image", "description": "Required scope: assets:write. Local-storage candidate only: accepts one multipart image field and registers it as an owned asset. This does not upload to R2, issue a presigned URL, start generation, call the Yuanjing image engine, or charge credits.", "x-required-scope": "assets:write", "x-storage-contract": "local_candidate_not_r2", "x-execution-started": false, "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "image" ], "additionalProperties": false, "properties": { "image": { "type": "string", "format": "binary" }, "role": { "type": "string", "enum": [ "product", "white_bg", "subject", "competitor", "reference", "style", "mixed_reference", "model_reference", "brand" ] }, "client_request_id": { "type": "string", "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Idempotent upload replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetUploadResponse" } } } }, "201": { "description": "Local image stored and asset registered; generation_started=false and credits_charged=0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetUploadResponse" } } } }, "400": { "description": "Invalid multipart body or filename" }, "409": { "description": "Idempotency key reused with different image content" }, "413": { "description": "Image bytes or dimensions exceed the configured limit" }, "415": { "description": "Unsupported, mismatched, animated, or undecodable image" } }, "operationId": "uploadAsset" } }, "/api/v1/assets/uploads/init": { "post": { "summary": "Initialize a private temporary R2 upload", "description": "Required scope: assets:write. Creates an owner-bound, short-lived presigned PUT contract for one JPG, PNG, or WEBP. The client must send the exact signed headers and bytes declared by filename, content_type, size, and sha256. The response contains no object key or permanent public URL. This does not start generation, call the Yuanjing image engine, reserve credits, or charge credits.", "x-required-scope": "assets:write", "x-storage-contract": "private_r2_temporary", "x-execution-started": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemporaryAssetUploadInitRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of an already completed upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemporaryAssetUploadInitResponse" } } } }, "201": { "description": "Short-lived private PUT contract created", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "upload" ], "properties": { "ok": { "const": true }, "upload": { "$ref": "#/components/schemas/TemporaryAssetUpload" } } } } } }, "400": { "description": "Invalid filename, size, SHA-256, role, or client_request_id" }, "409": { "description": "Idempotency key reused with different upload metadata, or upload already aborted" }, "413": { "description": "Declared image size exceeds the configured limit" }, "415": { "description": "Unsupported type or extension/type mismatch" }, "503": { "description": "Private R2 upload is not configured, presigning failed, or temporary upload state is unavailable. Upstream bucket, key, endpoint, and request details are not exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "initializeAssetUpload" } }, "/api/v1/assets/uploads/complete": { "post": { "summary": "Validate and complete a private temporary R2 upload", "description": "Required scope: assets:write. Owner-bound completion first compares R2 HEAD metadata with the server-side init record, then reads at most the configured image limit, recomputes SHA-256, and decodes the image to verify its real JPG/PNG/WEBP format and dimensions. Only validated bytes become a ready asset_id. No permanent public URL is returned and no generation or charge occurs.", "x-required-scope": "assets:write", "x-hash-verification": "streamed_sha256", "x-image-validation": "sharp_metadata", "x-execution-started": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemporaryAssetUploadOperationRequest" } } } }, "responses": { "200": { "description": "Stored bytes validated and asset registered, or an idempotent completion replay", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "upload", "asset", "idempotent_replay", "generation_started", "credits_charged" ], "properties": { "ok": { "const": true }, "upload": { "$ref": "#/components/schemas/TemporaryAssetUpload" }, "asset": { "$ref": "#/components/schemas/Asset" }, "idempotent_replay": { "type": "boolean" }, "generation_started": { "const": false }, "credits_charged": { "const": 0 } } } } } }, "404": { "description": "Owner-scoped upload or uploaded object not found" }, "409": { "description": "Upload expired/aborted, or stored type, length, metadata, or SHA-256 does not match init" }, "413": { "description": "Stored bytes or decoded dimensions exceed the configured limit" }, "415": { "description": "Stored bytes are undecodable, animated, or do not match the declared image type" }, "503": { "description": "Private R2 read or temporary state is unavailable. Upstream error details are redacted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "completeAssetUpload" } }, "/api/v1/assets/uploads/abort": { "post": { "summary": "Abort an owned private temporary upload", "description": "Required scope: assets:write. Deletes the owned pending or expired temporary object and records status=aborted. Repeated abort is idempotent. A completed upload cannot be aborted through this endpoint. No permanent public URL is returned.", "x-required-scope": "assets:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemporaryAssetUploadOperationRequest" } } } }, "responses": { "200": { "description": "Temporary upload aborted or idempotently already aborted", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "upload", "idempotent_replay" ], "properties": { "ok": { "const": true }, "upload": { "$ref": "#/components/schemas/TemporaryAssetUpload" }, "idempotent_replay": { "type": "boolean" } } } } } }, "404": { "description": "Owner-scoped upload not found" }, "409": { "description": "Upload is already completed" }, "503": { "description": "Private R2 deletion or temporary state is unavailable. Upstream error details are redacted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "abortAssetUpload" } }, "/api/v1/jobs/plan": { "post": { "summary": "Plan a job without executing it", "description": "Required scope: images:write; requests that reference asset IDs also require assets:read, and designer_id also requires designers:read. Planning only: this endpoint does not start generation, reserve or charge credits, or create an executable job. estimated_credits is informational; a versioned quote, explicit approval and atomic submit remain required before any enabled future execution flow.", "x-required-scope": "images:write", "x-planning-only": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPlanRequest" } } } }, "responses": { "200": { "description": "Planning-only result; no credits charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPlanResponse" } } } }, "400": { "description": "Invalid or ambiguous planning request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported or conflicting capability input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "planJob" } }, "/api/v1/plans/{planId}": { "get": { "summary": "Get one persisted planning draft", "description": "Required scope: images:write. Owner-scoped read of the current plan lifecycle state. This does not execute work or charge credits.", "x-required-scope": "images:write", "x-planning-only": true, "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Persisted plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPlanResponse" } } } }, "404": { "description": "Plan not found for this account" } }, "operationId": "getPlan" } }, "/api/v1/plans/{planId}/inputs": { "patch": { "summary": "Merge inputs into a persisted plan and recalculate", "description": "Required scope: images:write. Uses expected_version for optimistic concurrency, merges structured inputs, then recalculates missing fields and estimated credits. No generation starts and no credits are charged.", "x-required-scope": "images:write", "x-planning-only": true, "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanInputPatch" } } } }, "responses": { "200": { "description": "Updated persisted plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPlanResponse" } } } }, "404": { "description": "Plan not found for this account" }, "409": { "description": "Version conflict or plan already converted" }, "410": { "description": "Plan expired" } }, "operationId": "updatePlanInputs" } }, "/api/v1/jobs": { "post": { "summary": "Create a non-executing workflow job from a ready plan", "description": "Required scope: images:write. Converts an owned ready_for_quote plan into an awaiting_confirmation workflow job with planned output slots. This endpoint does not start execution, reserve credits or charge credits.", "x-required-scope": "images:write", "x-execution-started": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_request_id", "plan_id" ], "additionalProperties": false, "properties": { "client_request_id": { "type": "string", "maxLength": 128 }, "plan_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowJobResponse" } } } }, "201": { "description": "Workflow job created without execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowJobResponse" } } } }, "409": { "description": "Plan is not ready, already converted, or idempotency conflict" } }, "operationId": "createJob" }, "get": { "summary": "List owned workflow jobs", "description": "Required scope: images:write. These workflow jobs are planning/confirmation records only.", "x-required-scope": "images:write", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Workflow job list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowJobListResponse" } } } } }, "operationId": "listJobs" } }, "/api/v1/jobs/status-batch": { "post": { "summary": "Read up to 100 owned workflow jobs in one request", "description": "Required scope: images:write. Query-only batch status lookup for existing workflow Jobs. This operation never creates, submits, retries or charges a Job. Missing and non-owned IDs are returned together in missing_job_ids so ownership is not disclosed.", "x-required-scope": "images:write", "x-execution-started": false, "x-yuanjing-paid-send": false, "x-yuanjing-automatic-paid-retry": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "job_ids" ], "additionalProperties": false, "properties": { "job_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "minLength": 6, "maxLength": 128, "pattern": "^wjob_[A-Za-z0-9_-]+$" }, "description": "Existing workflow Job IDs. Duplicate values are returned once in first-seen order." } } } } } }, "responses": { "200": { "description": "Owned workflow Jobs in first-seen request order plus IDs that were missing or not owned", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "count", "missing_job_ids" ], "additionalProperties": false, "properties": { "object": { "const": "workflow_job_batch" }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/WorkflowJob" } }, "count": { "type": "integer", "minimum": 0, "maximum": 100 }, "missing_job_ids": { "type": "array", "maxItems": 100, "items": { "type": "string" } } } } } } }, "400": { "description": "job_ids is missing, invalid, or contains more than 100 items" } }, "operationId": "getJobStatusesBatch" } }, "/api/v1/jobs/{jobId}": { "get": { "summary": "Get one owned workflow job", "description": "Required scope: images:write.", "x-required-scope": "images:write", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow job", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "job": { "$ref": "#/components/schemas/WorkflowJob" } } } } } }, "404": { "description": "Workflow job not found" } }, "operationId": "getJob" } }, "/api/v1/jobs/{jobId}/outputs": { "get": { "summary": "List planned output slots for a workflow job", "description": "Required scope: images:write. Slots remain planned; this route does not generate images.", "x-required-scope": "images:write", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Planned output slot list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "job_id": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowOutputSlot" } }, "count": { "type": "integer" } } } } } }, "404": { "description": "Workflow job not found" } }, "operationId": "listJobOutputs" } }, "/api/v1/jobs/{jobId}/result": { "get": { "summary": "Get an owner-bound workflow result projection (candidate)", "description": "Required scope: images:write. Default-off local candidate gated by DEVELOPER_WORKFLOW_RESULTS_ENABLED. Returns stable artifact: references and finalized ledger evidence when available; never returns storage locators, private generation-node URLs or signed URLs.", "x-required-scope": "images:write", "x-candidate": true, "x-default-enabled": false, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow result projection", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "result" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "result": { "$ref": "#/components/schemas/WorkflowResult" } } } } } }, "404": { "description": "Candidate disabled or result not found" } }, "operationId": "getJobResult" } }, "/api/v1/jobs/{jobId}/manifest": { "get": { "summary": "Get an owner-bound workflow result manifest (candidate)", "description": "Required scope: images:write. Default-off local candidate gated by DEVELOPER_WORKFLOW_RESULTS_ENABLED. Reports slot, model-evidence, Artifact and settlement state without private locators.", "x-required-scope": "images:write", "x-candidate": true, "x-default-enabled": false, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow result manifest", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "manifest" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "manifest": { "$ref": "#/components/schemas/WorkflowResultManifest" } } } } } }, "404": { "description": "Candidate disabled or manifest not found" } }, "operationId": "getJobManifest" } }, "/api/v1/jobs/{jobId}/artifacts/{artifactId}": { "get": { "summary": "Get one owner-bound workflow Artifact (candidate)", "description": "Required scope: images:write. Default-off local candidate gated by DEVELOPER_WORKFLOW_RESULTS_ENABLED. Returns immutable public evidence and an opaque result_ref only.", "x-required-scope": "images:write", "x-candidate": true, "x-default-enabled": false, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow Artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowArtifactResponse" } } } }, "404": { "description": "Candidate disabled or Artifact not found" } }, "operationId": "getJobArtifact" } }, "/api/v1/jobs/{jobId}/artifacts/{artifactId}/download": { "post": { "summary": "Issue a single-use opaque Artifact download (candidate)", "description": "Required scope: images:write. Default-off local candidate requiring both result and Artifact-download flags. The returned relative URL expires in about five minutes, remains API-key authenticated and is single-use.", "x-required-scope": "images:write", "x-candidate": true, "x-default-enabled": false, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Opaque download grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "download": { "$ref": "#/components/schemas/WorkflowDownloadGrant" } } } } } }, "404": { "description": "Candidate disabled or Artifact not found" }, "410": { "description": "Artifact bytes no longer exist" } }, "operationId": "issueArtifactDownload" } }, "/api/v1/jobs/{jobId}/download-package": { "post": { "summary": "Issue a single-use opaque ZIP download (candidate)", "description": "Required scope: images:write. Default-off local candidate. Omit artifact_ids for all current Artifacts or provide an owner-bound subset. Partial workflow results can be packaged.", "x-required-scope": "images:write", "x-candidate": true, "x-default-enabled": false, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "artifact_ids": { "type": "array", "uniqueItems": true, "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Opaque ZIP download grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "package": { "$ref": "#/components/schemas/WorkflowDownloadGrant" } } } } } }, "404": { "description": "Candidate disabled or result not found" }, "410": { "description": "One or more Artifact objects no longer exist" } }, "operationId": "issueJobDownloadPackage" } }, "/api/v1/workflow-downloads/{token}": { "get": { "summary": "Redeem an authenticated single-use workflow download (candidate)", "description": "Required scope: images:write. The opaque token is owner-bound, short-lived and single-use. Keep the API Authorization header; do not treat this as a public browser URL.", "x-required-scope": "images:write", "x-candidate": true, "x-default-enabled": false, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "Image bytes or ZIP package", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Candidate disabled or token not found" }, "410": { "description": "Token expired/used or Artifact evidence no longer matches bytes" } }, "operationId": "redeemWorkflowDownload" } }, "/api/v1/jobs/{jobId}/confirm": { "post": { "summary": "Retired workflow confirmation route", "description": "Required scope: images:write. This compatibility route always returns 410 workflow_confirm_replaced_by_submit and changes no state. Use an active quote plus explicit approval with POST /api/v1/jobs/{jobId}/submit as the only confirmation path.", "x-required-scope": "images:write", "deprecated": true, "x-execution-started": false, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmed" ], "additionalProperties": false, "properties": { "confirmed": { "type": "boolean", "const": true } } } } } }, "responses": { "410": { "description": "workflow_confirm_replaced_by_submit; execution_started=false and credits_charged=0" } }, "operationId": "confirmJobLegacy" } }, "/api/v1/jobs/{jobId}/submit": { "post": { "summary": "Atomically reserve credits and queue an enabled image workflow (candidate)", "description": "Required scope: images:write. Default-off candidate gated by DEVELOPER_WORKFLOW_SUBMIT_ENABLED. The exact capability must report workflow_execution_status=enabled; commerce capabilities additionally require DEVELOPER_COMMERCE_EXECUTION_ENABLED. With a same-SQLite deployment, one transaction binds the active quote/job versions, reserves exact per-slot credits, confirms the Job and activates its staged dispatch. confirmed=true remains the default path. When AGENT_APPROVAL_POLICIES_ENABLED=true, approval_policy_id may replace that confirmation only inside its connection/capability/time/credit/output bounds, with an atomic monotonic reservation. A timeout is not permission to submit again: query the same Job.", "x-required-scope": "images:write", "x-candidate": true, "x-default-enabled": false, "x-authorization-modes": [ "explicit_confirmation", "bounded_policy" ], "x-explicit-confirmation-required": true, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowSubmitRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of the exact existing reservation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowSubmitResponse" } } } }, "202": { "description": "Credits reserved and dispatch queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowSubmitResponse" } } } }, "402": { "description": "Insufficient credits" }, "404": { "description": "Candidate disabled" }, "409": { "description": "Confirmation, quote, version, price, snapshot or idempotency conflict" }, "503": { "description": "Atomic same-SQLite reservation or staged dispatch unavailable" } }, "operationId": "submitJob" } }, "/api/v1/jobs/{jobId}/quotes": { "post": { "summary": "Create a time-limited authoritative price quote", "description": "Required scope: images:write. Locks the owner-bound price and immutable Job version/snapshot until expires_at. Quote creation itself does not reserve credits, start execution, call the Yuanjing image engine or charge credits. Only the separate default-off submit candidate can atomically reserve an active workflow quote when that capability is enabled.", "x-required-scope": "images:write", "x-authoritative-scope": "price_and_job_snapshot_until_expiry", "x-credits-reserved": 0, "x-execution-started": false, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_request_id" ], "additionalProperties": false, "properties": { "client_request_id": { "type": "string", "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowQuoteResponse" } } } }, "201": { "description": "Price-only quote created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowQuoteResponse" } } } }, "404": { "description": "Workflow job not found for this account" }, "409": { "description": "Job not quotable or idempotency conflict" } }, "operationId": "createJobQuote" } }, "/api/v1/quotes/{quoteId}": { "get": { "summary": "Get one owned workflow quote", "description": "Required scope: images:write. Returns active, expired, superseded or submitted owner-bound quote state. Quote creation alone implies no reservation; a submitted quote reports its persisted Reservation.", "x-required-scope": "images:write", "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owned quote", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "quote": { "$ref": "#/components/schemas/WorkflowQuote" } } } } } }, "404": { "description": "Quote not found for this account" } }, "operationId": "getQuote" } }, "/api/v1/jobs/{jobId}/recovery-plan": { "post": { "summary": "Build a contract-only missing-slot recovery plan", "description": "Required scope: images:write. Inspects current output-slot state and records a manual recovery plan. Contract-only: zero image-engine calls, no execution, and zero credits charged. It does not retry or repair any slot.", "x-required-scope": "images:write", "x-orchestration-contract-only": true, "x-engine-calls": 0, "x-execution-started": false, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_request_id" ], "additionalProperties": false, "properties": { "client_request_id": { "type": "string", "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRecoveryPlanResponse" } } } }, "201": { "description": "Recovery contract recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRecoveryPlanResponse" } } } }, "404": { "description": "Workflow job not found" }, "409": { "description": "Job has no execution state to recover" } }, "operationId": "createJobRecoveryPlan" } }, "/api/v1/jobs/{jobId}/slot-retry": { "post": { "summary": "Re-queue retryable failed slots under an open reservation", "description": "Required scope: images:write. Re-queues retryable failed output slots while the workflow credit reservation remains reserved. Uses server-stored slot_requests only; client prompts are rejected. expected_credits must be 0 (no new reservation). Settled or refunded reservations return 409 workflow_slot_retry_settled.", "x-required-scope": "images:write", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_request_id", "confirmed", "expected_credits" ], "additionalProperties": false, "properties": { "client_request_id": { "type": "string", "maxLength": 128 }, "confirmed": { "type": "boolean", "const": true }, "expected_credits": { "type": "integer", "const": 0 }, "slot_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 64 } } } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowSlotRetryResponse" } } } }, "202": { "description": "Slots re-queued for manual recovery dispatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowSlotRetryResponse" } } } }, "404": { "description": "Workflow job not found" }, "409": { "description": "Reservation settled, slots not retryable, or outbox still leased" }, "422": { "description": "Unsupported fields such as prompt" } }, "operationId": "retryJobSlots" } }, "/api/v1/jobs/{jobId}/manual-handoff": { "post": { "summary": "Record a contract-only manual handoff request", "description": "Required scope: images:write. Records that operator review is required and marks unfinished slots for manual action. Contract-only: zero image-engine calls, no external operator is contacted, no execution starts, and zero credits are charged.", "x-required-scope": "images:write", "x-orchestration-contract-only": true, "x-engine-calls": 0, "x-execution-started": false, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_request_id" ], "additionalProperties": false, "properties": { "client_request_id": { "type": "string", "maxLength": 128 }, "reason": { "type": "string", "enum": [ "non_retryable_failure", "retry_exhausted", "user_requested", "operator_review" ] } } } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowManualHandoffResponse" } } } }, "201": { "description": "Manual handoff contract recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowManualHandoffResponse" } } } }, "404": { "description": "Workflow job not found" }, "409": { "description": "Job is not handoffable or a conflicting handoff exists" } }, "operationId": "createJobManualHandoff" } }, "/api/v1/images/generations": { "post": { "summary": "Submit standalone image generation under explicit or bounded authorization", "description": "Required scope: images:write. This is an executable, potentially billable endpoint and is separate from POST /api/v1/jobs/plan. Before submission, obtain an exact current price. confirmed=true remains the default path. When AGENT_APPROVAL_POLICIES_ENABLED=true, approval_policy_id may replace that confirmation only inside its connection/capability/time/credit/output bounds; the server atomically and monotonically reserves policy capacity against the stable request fingerprint. The request is fail-closed: fields outside GenerationRequest, including asset_ids, designer_id and capability_id, return unsupported_field and are never silently ignored. A timeout is not permission to submit again: query the same task/client request ID.", "x-required-scope": "images:write", "x-authorization-modes": [ "explicit_confirmation", "bounded_policy" ], "x-explicit-confirmation-required": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of the same client_request_id and identical request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationSubmissionResponse" } } } }, "202": { "description": "Confirmed task queued with service/capability identity, planned parameters, estimated credits, and no unproven effective-model claim", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationSubmissionResponse" }, "example": { "ok": true, "task_id": "gentask_01", "client_request_id": "client-20260714-001", "status": "queued", "idempotent_replay": false, "service_name": "源景 AI", "engine_name": "源景图像生成引擎", "router_name": "源景智能路由", "capability_id": "image.free-generation", "capability_name": "自由生图", "planned_model": "gpt-image-2.0", "aspect_ratio": "1:1", "image_size": "1K", "requested_count": 1, "estimated_credits": 100, "effective_model": null, "effective_model_status": "pending_execution_evidence" } } } }, "409": { "description": "generation_confirmation_required when confirmed=true/expected_credits is missing, or generation_price_changed when current authoritative credits differ from expected_credits. Show the new price and obtain a new explicit confirmation; do not silently resubmit.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "generation_confirmation_required", "generation_price_changed", "idempotency_conflict" ] } } } ] }, "examples": { "generation_confirmation_required": { "value": { "error": "Explicit confirmation is required", "code": "generation_confirmation_required" } }, "generation_price_changed": { "value": { "error": "Generation price changed", "code": "generation_price_changed" } } } } } }, "422": { "description": "unsupported_field: one or more request fields are not part of standalone GenerationRequest and none are silently ignored.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "required": [ "unsupported_fields" ], "properties": { "code": { "type": "string", "const": "unsupported_field" }, "unsupported_fields": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } } } } ] }, "example": { "error": "Unsupported generation request field: asset_ids", "code": "unsupported_field", "unsupported_fields": [ "asset_ids" ] } } } } }, "operationId": "createImageGeneration", "tags": [ "创建图片任务", "图片模型" ], "x-yuanjing-paid-send": true, "x-yuanjing-docs-pair": "GET /api/v1/tasks/{taskId}" } }, "/api/v1/tasks": { "get": { "summary": "List tasks", "description": "Required scope: images:write.", "x-required-scope": "images:write", "responses": { "200": { "description": "Task list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskListResponse" } } } } }, "operationId": "listTasks" } }, "/api/v1/tasks/{taskId}": { "get": { "summary": "Get task", "description": "Required scope: images:write.\n\n任务状态包含：running、background_processing、succeeded、partial_success、failed、reconciliation_required。超时继续查询同一 task_id，不得重新 POST。", "x-required-scope": "images:write", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "404": { "description": "Not found" } }, "operationId": "getTask", "tags": [ "查询结果" ], "x-yuanjing-docs-pair": "POST /api/v1/images/generations" } }, "/api/v1/tasks/{taskId}/retry": { "post": { "summary": "Retry as a new paid generation", "description": "Required scope: images:write. A retry is a new potentially billable attempt. Show the original task's safe price summary, obtain explicit approval, then send confirmed=true and the approved expected_credits. The summary exposes only billing-safe fields and never provider prompts, credentials or internal request IDs.", "x-required-scope": "images:write", "x-explicit-confirmation-required": true, "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryGenerationRequest" } } } }, "responses": { "202": { "description": "Confirmed retry queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRetryResponse" } } } }, "409": { "description": "retry_confirmation_required when confirmed=true/expected_credits is missing, or generation_price_changed when current authoritative credits differ. Return only a safe current price summary, show it to the user, and obtain a new explicit confirmation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "retry_confirmation_required", "generation_price_changed" ] }, "price_summary": { "type": "object", "description": "Billing-safe retry summary without provider or internal workflow fields.", "properties": { "model": { "type": "string" }, "image_size": { "type": "string" }, "count": { "type": "integer", "minimum": 1 }, "expected_credits": { "type": "integer", "minimum": 0 }, "current_credits": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } } } ] }, "examples": { "retry_confirmation_required": { "value": { "error": "Retry confirmation is required", "code": "retry_confirmation_required", "price_summary": { "model": "gpt-image-2.0", "image_size": "1K", "count": 1, "expected_credits": 100, "current_credits": 100 } } }, "generation_price_changed": { "value": { "error": "Generation price changed", "code": "generation_price_changed", "price_summary": { "model": "gpt-image-2.0", "image_size": "1K", "count": 1, "expected_credits": 100, "current_credits": 120 } } } } } } } }, "operationId": "retryTask" } }, "/api/v1/agent/capability-map": { "get": { "summary": "List Agent-readable website capability and form map", "description": "Required scope: models:read. Returns a unified map of Yuanjing website image features, workflow capabilities, recipes, and owner resources with Chinese names, aliases, forms, and executor bindings. Feature flags affect only Agent surfaces; ordinary website users are unaffected. Does not expose providers, Dify, prompts, R2, or secrets.", "x-required-scope": "models:read", "operationId": "listAgentCapabilityMap", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "website_feature_id", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search Chinese name, alias, or capability id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "count", "data", "secrets_printed", "ordinary_users_unaffected" ], "properties": { "object": { "type": "string", "const": "agent_capability_map" }, "count": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "secrets_printed": { "type": "boolean", "const": false }, "ordinary_users_unaffected": { "type": "boolean", "const": true } } } } } }, "401": { "description": "Invalid developer key" }, "403": { "description": "Missing required scope" } } } }, "/api/v1/agent/forms/{capabilityId}": { "get": { "summary": "Get Agent form for one capability", "description": "Required scope: models:read. Returns required and optional fields with x_question prompts for conversational Agent form filling.", "x-required-scope": "models:read", "operationId": "getAgentCapabilityForm", "parameters": [ { "name": "capabilityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "capability_id", "name" ], "properties": { "object": { "type": "string", "const": "agent_form" }, "capability_id": { "type": "string" }, "name": { "type": "string" }, "required": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "optional": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "execution": { "type": "object", "additionalProperties": true } } } } } }, "404": { "description": "Capability form not found" } } } }, "/api/v1/agent/playbook": { "get": { "summary": "Get Agent auth and execution playbook", "description": "Required scope: models:read. Documents Bearer auth, balance, workflow plan→quote→submit→query→download, site-feature quote/submit, designers and custom skills. No secrets.", "x-required-scope": "models:read", "operationId": "getAgentPlaybook", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "auth", "identity_and_balance", "workflow_call_sequence", "safety" ], "properties": { "object": { "type": "string", "const": "agent_auth_playbook" }, "auth": { "type": "object", "additionalProperties": true }, "identity_and_balance": { "type": "object", "additionalProperties": true }, "workflow_call_sequence": { "type": "array", "items": { "type": "string" } }, "site_feature_call_sequence": { "type": "array", "items": { "type": "string" } }, "safety": { "type": "object", "additionalProperties": true }, "pricing_source": { "type": "string" }, "models": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } } }, "/api/v1/agent/site-features/{featureId}/quote": { "post": { "summary": "Authoritative zero-charge quote for a website site_generate feature", "description": "Required scope: images:write. Quotes credits via the same chargeParamsFromWorkflowBody used by the website. Does not reserve balance, call providers, or start generation. Non-gpt-image features require DEVELOPER_AGENT_SITE_FEATURES_ENABLED; the flag does not affect ordinary website users.", "x-required-scope": "images:write", "operationId": "quoteAgentSiteFeature", "parameters": [ { "name": "featureId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Website feature id such as poster, fashion, selfmedia-article, matting-refine, or gpt-image" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_request_id", "prompt" ], "properties": { "client_request_id": { "type": "string", "maxLength": 128 }, "prompt": { "type": "string", "maxLength": 4000 }, "model": { "type": "string" }, "aspect_ratio": { "type": "string" }, "image_size": { "type": "string" }, "n": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "feature", "quote", "confirmation_required", "secrets_printed" ], "properties": { "ok": { "type": "boolean" }, "feature": { "type": "object", "additionalProperties": true }, "quote": { "type": "object", "additionalProperties": true }, "confirmation_required": { "type": "boolean" }, "secrets_printed": { "type": "boolean", "const": false } } } } } }, "404": { "description": "Feature not found or Agent site features disabled" } } } }, "/api/v1/agent/site-features/{featureId}/submit": { "post": { "summary": "Confirm and submit a website site_generate feature via existing generate executor", "description": "Required scope: images:write. Requires confirmed=true and expected_credits matching the authoritative quote. Reuses developer task store and routes/generate.js#handleGenerateRequest. Non-gpt-image features require DEVELOPER_AGENT_SITE_FEATURES_ENABLED.", "x-required-scope": "images:write", "operationId": "submitAgentSiteFeature", "parameters": [ { "name": "featureId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_request_id", "prompt", "confirmed", "expected_credits" ], "properties": { "client_request_id": { "type": "string", "maxLength": 128 }, "prompt": { "type": "string", "maxLength": 4000 }, "model": { "type": "string" }, "aspect_ratio": { "type": "string" }, "image_size": { "type": "string" }, "n": { "type": "integer", "minimum": 1 }, "confirmed": { "type": "boolean", "const": true }, "expected_credits": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "task_id", "status", "estimated_credits", "secrets_printed" ], "properties": { "ok": { "type": "boolean" }, "task_id": { "type": "string" }, "client_request_id": { "type": "string" }, "status": { "type": "string" }, "idempotent_replay": { "type": "boolean" }, "capability_id": { "type": "string" }, "website_feature_id": { "type": "string" }, "estimated_credits": { "type": "integer" }, "secrets_printed": { "type": "boolean", "const": false } } } } } }, "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "task_id", "status", "estimated_credits", "secrets_printed" ], "properties": { "ok": { "type": "boolean" }, "task_id": { "type": "string" }, "client_request_id": { "type": "string" }, "status": { "type": "string" }, "idempotent_replay": { "type": "boolean" }, "capability_id": { "type": "string" }, "website_feature_id": { "type": "string" }, "estimated_credits": { "type": "integer" }, "secrets_printed": { "type": "boolean", "const": false } } } } } }, "402": { "description": "Insufficient balance" }, "409": { "description": "Confirmation or price conflict" } } } }, "/.well-known/agent-skill.json": { "get": { "tags": [ "Agent Skill", "快速开始" ], "summary": "公开 Agent Skill 标准发现别名", "description": "返回与 /.well-known/yuanjing-agent-skill.json 相同的无凭据、带完整性信息的发现清单。", "operationId": "getStandardAgentSkillManifest", "security": [], "responses": { "200": { "description": "发现清单", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillManifest" } } } } } } }, "/.well-known/yuanjing-agent-skill.json": { "get": { "tags": [ "Agent Skill", "快速开始" ], "summary": "公开 Agent Skill 发现清单", "description": "不含任何用户凭据或供应商密钥。安装方须校验 package sha256。", "operationId": "getYuanjingAgentSkillManifest", "security": [], "responses": { "200": { "description": "发现清单", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillManifest" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } } } }, "/api/v1/agent-connections/device/start": { "post": { "tags": [ "认证与连接", "快速开始" ], "summary": "启动 Device Code + PKCE 连接", "description": "返回 device_code 与 user_code。服务端只存哈希。", "operationId": "startAgentDeviceAuthorization", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceStartRequest" } } } }, "responses": { "200": { "description": "设备授权已启动", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceStartResponse" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } } } }, "/api/v1/agent-connections/device/status": { "get": { "tags": [ "认证与连接" ], "summary": "查询 Device 授权状态", "description": "不返回完整 Key。可用于安全调试轮询。", "operationId": "getAgentDeviceAuthorizationStatus", "security": [], "parameters": [ { "name": "device_code", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "pending / approved / expired / consumed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "approved", "expired", "consumed", "denied" ] }, "expires_in": { "type": "integer" } } } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } } } }, "/api/v1/agent-connections/device/token": { "post": { "tags": [ "认证与连接" ], "summary": "用 PKCE verifier 交换一次性 Developer Key", "description": "成功后 device_code 立即消费。错误 verifier、过期、重放分别返回 422/410/409。完整 Key 仅此一次。", "operationId": "exchangeAgentDeviceToken", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceTokenRequest" } } } }, "responses": { "200": { "description": "交换成功；access_token 仅返回一次", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceTokenResponse" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } }, "x-yuanjing-paid-send": false } }, "/api/v1/agent-approval-policy-intents": { "post": { "tags": [ "认证与连接" ], "summary": "Agent 请求一个待网页登录确认的有界授权", "description": "Developer Key 只能为自身所属的活跃连接创建 pending intent，不能自行激活或扩大付费权限。intent 十分钟过期。", "operationId": "createAgentApprovalPolicyIntent", "security": [ { "bearerAuth": [] } ], "x-required-scope": "images:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "capabilities", "max_credits_per_job", "daily_credit_limit", "total_credit_limit", "max_outputs_per_job", "total_output_limit", "expires_at" ], "properties": { "connection_id": { "type": "string" }, "capabilities": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "max_credits_per_job": { "type": "integer", "minimum": 0 }, "daily_credit_limit": { "type": "integer", "minimum": 0 }, "total_credit_limit": { "type": "integer", "minimum": 0 }, "max_outputs_per_job": { "type": "integer", "minimum": 1 }, "total_output_limit": { "type": "integer", "minimum": 1 }, "timezone": { "type": "string", "default": "Asia/Shanghai" }, "valid_from": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "等待网页登录账户确认", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "intent": { "$ref": "#/components/schemas/AgentApprovalPolicyIntent" } } } } } }, "404": { "description": "功能默认关闭" }, "409": { "description": "连接与 Developer Key 不匹配" } } } }, "/api/v1/agent-approval-policy-intents/{id}": { "get": { "tags": [ "认证与连接" ], "summary": "Agent 查询自身授权请求状态", "operationId": "getAgentApprovalPolicyIntent", "security": [ { "bearerAuth": [] } ], "x-required-scope": "images:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "不含账户密钥的 intent 状态", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "intent": { "$ref": "#/components/schemas/AgentApprovalPolicyIntent" } } } } } }, "404": { "description": "不存在或不属于当前连接" } } } }, "/api/account/agent-approval-policy-intents/{id}/approve": { "post": { "tags": [ "认证与连接" ], "summary": "网页登录账户一次确认并激活有界授权", "description": "只有 intent 所属的登录账户可以批准；批准前再次校验连接仍活跃且 Developer Key 未变化。", "operationId": "approveAgentApprovalPolicyIntent", "security": [ { "accountBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "授权已原子激活", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "policy": { "$ref": "#/components/schemas/AgentApprovalPolicy" } } } } } }, "409": { "description": "intent 过期、已取消或连接发生变化" } } } }, "/api/account/agent-approval-policy-intents/{id}": { "get": { "tags": [ "认证与连接" ], "summary": "网页登录账户读取待确认授权的完整边界", "operationId": "getAccountAgentApprovalPolicyIntent", "security": [ { "accountBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "仅返回本账户 intent 及可展示的授权边界，不含密钥", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "intent": { "$ref": "#/components/schemas/AgentApprovalPolicyIntent" } } } } } }, "404": { "description": "功能关闭或 intent 不属于当前账户" } } } }, "/api/account/agent-approval-policies": { "get": { "tags": [ "认证与连接" ], "summary": "列出当前账户的有界免确认授权", "operationId": "listAgentApprovalPolicies", "security": [ { "accountBearer": [] } ], "parameters": [ { "name": "connection_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "授权列表与已原子预占的额度", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/AgentApprovalPolicy" } } } } } } }, "404": { "description": "AGENT_APPROVAL_POLICIES_ENABLED 默认关闭" } } }, "post": { "tags": [ "认证与连接" ], "summary": "为一个活跃 Agent 连接创建有界免确认授权", "description": "账户级显式操作。不能授权重试、退款、支付、充值或调账；扩大额度需创建新的明确授权。", "operationId": "createAgentApprovalPolicy", "security": [ { "accountBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "connection_id", "capabilities", "max_credits_per_job", "daily_credit_limit", "total_credit_limit", "max_outputs_per_job", "total_output_limit", "expires_at" ], "properties": { "connection_id": { "type": "string" }, "capabilities": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "max_credits_per_job": { "type": "integer", "minimum": 0 }, "daily_credit_limit": { "type": "integer", "minimum": 0 }, "total_credit_limit": { "type": "integer", "minimum": 0 }, "max_outputs_per_job": { "type": "integer", "minimum": 1 }, "total_output_limit": { "type": "integer", "minimum": 1 }, "timezone": { "type": "string", "default": "Asia/Shanghai" }, "valid_from": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "授权已创建", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "policy": { "$ref": "#/components/schemas/AgentApprovalPolicy" } } } } } }, "404": { "description": "功能关闭或连接不存在" } } } }, "/api/account/agent-approval-policies/{id}": { "delete": { "tags": [ "认证与连接" ], "summary": "立即撤销有界免确认授权", "operationId": "revokeAgentApprovalPolicy", "security": [ { "accountBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "授权已撤销", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "policy": { "$ref": "#/components/schemas/AgentApprovalPolicy" } } } } } }, "404": { "description": "功能关闭或授权不存在" } } } }, "/api/account/agent-connections": { "get": { "tags": [ "认证与连接" ], "summary": "列出当前账户的 Agent 连接", "operationId": "listAccountAgentConnections", "security": [ { "accountBearer": [] } ], "responses": { "200": { "description": "连接列表（不含密钥）", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConnection" } } } } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } } } }, "/api/account/agent-connections/device/approve": { "post": { "tags": [ "认证与连接" ], "summary": "网站登录态批准 Device 用户码", "description": "绑定当前登录用户；不返回完整 Developer Key。", "operationId": "approveAccountAgentDevice", "security": [ { "accountBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_code" ], "properties": { "user_code": { "type": "string", "example": "ABCD-EFGH" } } } } } }, "responses": { "200": { "description": "已批准，等待 Agent 端换票", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceApprovalResponse" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } } } }, "/api/account/agent-connections/{id}/pause": { "post": { "tags": [ "认证与连接" ], "summary": "暂停 Agent 连接", "operationId": "pauseAccountAgentConnection", "security": [ { "accountBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "已暂停", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnectionMutationResponse" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } } } }, "/api/account/agent-connections/{id}/resume": { "post": { "tags": [ "认证与连接" ], "summary": "恢复 Agent 连接", "operationId": "resumeAccountAgentConnection", "security": [ { "accountBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "已恢复", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnectionMutationResponse" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } } } }, "/api/account/agent-connections/{id}": { "delete": { "tags": [ "认证与连接" ], "summary": "撤销 Agent 连接", "operationId": "revokeAccountAgentConnection", "security": [ { "accountBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "已撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnectionMutationResponse" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } } } }, "/api/v1/jobs/intake": { "post": { "tags": [ "电商工作流", "快速开始" ], "summary": "一句话识图补表（不扣费）", "description": "高置信度可见属性可自动接受；材质/容量/功效等商业事实不确定时进入 missing_fields；risky_claims 单独列出。同一 client_request_id 幂等。", "operationId": "intakeDeveloperJob", "security": [ { "bearerAuth": [] } ], "x-required-scopes-any-of": [ "models:read", "assets:read", "images:write" ], "x-yuanjing-paid-send": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobIntakeRequest" } } } }, "responses": { "200": { "description": "补表结果与确认卡", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobIntakeResponse" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } } } }, "/api/v1/jobs/{jobId}/result-audit": { "post": { "tags": [ "结果审计", "电商工作流" ], "summary": "对已交付槽位做结果审计", "description": "受 DEVELOPER_RESULT_AUDIT_ENABLED 控制（默认关闭）。确定性失败 authority=server_verified；Agent 视觉判断 authority=agent_advisory 且 can_trigger_free_repair=false。客观修复另受 DEVELOPER_OBJECTIVE_REPAIR_ENABLED。", "operationId": "auditDeveloperJobResults", "security": [ { "bearerAuth": [] } ], "x-required-scope": "images:write", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultAuditRequest" } } } }, "responses": { "200": { "description": "审计报告", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultAuditResponse" } } } }, "202": { "description": "已进入 repair_queued（仅当客观修复 flag 开启）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultAuditResponse" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } } } }, "/api/v1/shop-panel/prompt-reverse": { "post": { "tags": [ "Shop Panel", "Agent" ], "summary": "竞品反推提示词（扣点）", "description": "Developer Key facade. Bills the bound user account. Requires confirmed=true and expected_credits matching image count × 100. Taobao/Tmall HTTPS URLs or imagesBase64.", "operationId": "createShopPanelPromptReverse", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "images:write" ], "x-yuanjing-paid-send": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "": "#/components/schemas/ShopPanelPromptReverseRequest" } } } }, "responses": { "200": { "description": "Prompt reverse results", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "chargedCredits": { "type": "integer" }, "pricing": { "type": "object", "additionalProperties": true } } } } } }, "207": { "description": "Partial success with refund", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "chargedCredits": { "type": "integer" }, "pricing": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Developer API disabled", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Confirmation required / price changed / duplicate", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "502": { "description": "Upstream failed", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } } } } }, "/api/v1/shop-panel/business-playbook": { "post": { "tags": [ "Shop Panel", "Agent" ], "summary": "提炼商业打法（扣点）", "description": "Developer Key facade. Fixed 100 credits per call. Requires confirmed=true and expected_credits=100.", "operationId": "createShopPanelBusinessPlaybook", "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "images:write" ], "x-yuanjing-paid-send": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "": "#/components/schemas/ShopPanelBusinessPlaybookRequest" } } } }, "responses": { "200": { "description": "Business playbook text", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "chargedCredits": { "type": "integer" }, "pricing": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "402": { "description": "Insufficient balance", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "Developer API disabled", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "409": { "description": "Confirmation required / price changed / duplicate", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "502": { "description": "Upstream failed", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "": "#/components/schemas/ErrorBody" } } } } } } }, "/api/v1/agent-connections/{connectionId}/activate": { "post": { "tags": [ "认证与连接" ], "summary": "确认本机安全落盘与只读自检完成", "description": "Device token 交换后的连接先处于 pending_activation；本机安全保存并完成只读自检后才激活写权限。", "operationId": "activateAgentConnection", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "连接已激活", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnection" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } }, "x-yuanjing-paid-send": false } }, "/api/v1/agent-connections/{connectionId}/abort": { "post": { "tags": [ "认证与连接" ], "summary": "取消尚未完成的本机连接", "description": "本机凭据保存或只读自检失败时撤销 pending credential；即使客户端崩溃，pending credential 也会自动过期。", "operationId": "abortPendingAgentConnection", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "待激活连接已撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnection" } } } }, "400": { "description": "请求参数非法", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Invalid request", "code": "invalid_request" } } } }, "401": { "description": "未认证", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "权限不足或功能关闭", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Forbidden", "code": "insufficient_scope" } } } }, "404": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Not found", "code": "not_found" } } } }, "409": { "description": "冲突 / 幂等冲突 / 重放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Already used", "code": "replay_detected" } } } }, "410": { "description": "已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Expired", "code": "device_code_expired" } } } }, "422": { "description": "语义不可处理（如 PKCE 校验失败）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "PKCE verification failed", "code": "invalid_grant" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "error": "Too many requests", "code": "rate_limited" } } } } }, "x-yuanjing-paid-send": false } }, "/api/v1/agent/videos/options": { "get": { "x-required-scope": "videos:write", "security": [ { "bearerAuth": [] } ], "tags": [ "Agent ??" ], "operationId": "getAgentVideoOptions", "summary": "?????????", "responses": { "200": { "description": "??", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Capability disabled or insufficient scope" }, "409": { "description": "Exact quote confirmation required or state conflict" }, "429": { "description": "Rate limited" } }, "x-yuanjing-zero-charge": true } }, "/api/v1/agent/videos/quote": { "post": { "x-required-scope": "videos:write", "security": [ { "bearerAuth": [] } ], "tags": [ "Agent ??" ], "operationId": "quoteAgentVideo", "summary": "??????", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVideoRequest" } } } }, "responses": { "200": { "description": "??", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Capability disabled or insufficient scope" }, "409": { "description": "Exact quote confirmation required or state conflict" }, "429": { "description": "Rate limited" } }, "x-yuanjing-zero-charge": true } }, "/api/v1/agent/videos/submit": { "post": { "x-required-scope": "videos:write", "security": [ { "bearerAuth": [] } ], "tags": [ "Agent ??" ], "operationId": "submitAgentVideo", "summary": "?????????", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVideoConfirmedRequest" } } } }, "responses": { "200": { "description": "??", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Capability disabled or insufficient scope" }, "409": { "description": "Exact quote confirmation required or state conflict" }, "429": { "description": "Rate limited" } }, "x-yuanjing-paid-send": true, "x-yuanjing-automatic-paid-retry": false } }, "/api/v1/agent/videos/tasks/{jobId}": { "get": { "x-required-scope": "videos:write", "security": [ { "bearerAuth": [] } ], "tags": [ "Agent ??" ], "operationId": "getAgentVideoTask", "summary": "??????", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "??", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Capability disabled or insufficient scope" }, "409": { "description": "Exact quote confirmation required or state conflict" }, "429": { "description": "Rate limited" } }, "x-yuanjing-zero-charge": true } }, "/api/v1/agent/one-click-video/options": { "get": { "x-required-scope": "videos:write", "security": [ { "bearerAuth": [] } ], "tags": [ "Agent ??" ], "operationId": "getAgentOneClickVideoOptions", "summary": "???????????", "responses": { "200": { "description": "??", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Capability disabled or insufficient scope" }, "409": { "description": "Exact quote confirmation required or state conflict" }, "429": { "description": "Rate limited" } }, "x-yuanjing-zero-charge": true } }, "/api/v1/agent/one-click-video/storyboard/quote": { "post": { "x-required-scope": "videos:write", "security": [ { "bearerAuth": [] } ], "tags": [ "Agent ??" ], "operationId": "quoteAgentOneClickStoryboard", "summary": "????????", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOneClickStoryboardRequest" } } } }, "responses": { "200": { "description": "??", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Capability disabled or insufficient scope" }, "409": { "description": "Exact quote confirmation required or state conflict" }, "429": { "description": "Rate limited" } }, "x-yuanjing-zero-charge": true } }, "/api/v1/agent/one-click-video/storyboard/submit": { "post": { "x-required-scope": "videos:write", "security": [ { "bearerAuth": [] } ], "tags": [ "Agent ??" ], "operationId": "submitAgentOneClickStoryboard", "summary": "???????????", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOneClickStoryboardConfirmedRequest" } } } }, "responses": { "200": { "description": "??", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Capability disabled or insufficient scope" }, "409": { "description": "Exact quote confirmation required or state conflict" }, "429": { "description": "Rate limited" } }, "x-yuanjing-paid-send": true, "x-yuanjing-automatic-paid-retry": false } }, "/api/v1/agent/one-click-video/render/quote": { "post": { "x-required-scope": "videos:write", "security": [ { "bearerAuth": [] } ], "tags": [ "Agent ??" ], "operationId": "quoteAgentOneClickRender", "summary": "????????", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOneClickRenderRequest" } } } }, "responses": { "200": { "description": "??", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Capability disabled or insufficient scope" }, "409": { "description": "Exact quote confirmation required or state conflict" }, "429": { "description": "Rate limited" } }, "x-yuanjing-zero-charge": true } }, "/api/v1/agent/one-click-video/render/submit": { "post": { "x-required-scope": "videos:write", "security": [ { "bearerAuth": [] } ], "tags": [ "Agent ??" ], "operationId": "submitAgentOneClickRender", "summary": "???????????", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOneClickRenderConfirmedRequest" } } } }, "responses": { "200": { "description": "??", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Capability disabled or insufficient scope" }, "409": { "description": "Exact quote confirmation required or state conflict" }, "429": { "description": "Rate limited" } }, "x-yuanjing-paid-send": true, "x-yuanjing-automatic-paid-retry": false } }, "/api/v1/agent/one-click-video/tasks/{jobId}": { "get": { "x-required-scope": "videos:write", "security": [ { "bearerAuth": [] } ], "tags": [ "Agent ??" ], "operationId": "getAgentOneClickVideoTask", "summary": "????????", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "??", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Capability disabled or insufficient scope" }, "409": { "description": "Exact quote confirmation required or state conflict" }, "429": { "description": "Rate limited" } }, "x-yuanjing-zero-charge": true } } }, "tags": [ { "name": "快速开始", "description": "发现清单、连接与自检入口" }, { "name": "认证与连接", "description": "Device Code + PKCE 与账户侧连接管理" }, { "name": "图片模型", "description": "源景 G2 / G2-PRO / N2 / N2-PRO；价格以 GET /api/v1/models 为准" }, { "name": "创建图片任务", "description": "确认报价后提交生成" }, { "name": "查询结果", "description": "按原 task_id 轮询，超时不得重提" }, { "name": "素材", "description": "素材登记与生命周期" }, { "name": "电商工作流", "description": "规划、报价、提交与 intake" }, { "name": "账户与用量", "description": "余额与用量" }, { "name": "Agent Skill", "description": "Skill 发现与安装" }, { "name": "错误码", "description": "常见错误与安全边界" }, { "name": "结果审计", "description": "确定性审计与客观修复合同（默认关闭）" }, { "name": "Agent ??", "description": "Agent ?????????????????????????????????" } ] }