{"openapi":"3.1.0","info":{"title":"源景 AI 开发者 API","version":"1.6.0","description":"## 先能生图，再查结果返图\n\n1. 开发者中心拿 Key（或 Agent Skill 连上）→ `YUANJING_API_KEY`\n2. `POST /api/v1/images/generations`：`model` + `prompt`（可选 `aspect_ratio` / `image_size` / `n`）\n3. `GET /api/v1/tasks/{taskId}`：`terminal_status=true` 且有图片时取 `task.images[0].url`\n\n可选：`GET /api/v1/models` 看模型列表。调用面与 GRSAI 同类。\n\nBase：`https://yuanjing-ai.com` · Auth：`Bearer yj_live_...`\n不含网站主图/详情等工作流。完整包 `/openapi.json`。"},"servers":[{"url":"https://yuanjing-ai.com"}],"tags":[{"name":"源景图片生成","description":"主路径：①创建任务 → ②查结果返图"},{"name":"源景视频生成","description":"次要：报价 → 提交 → 查结果（不影响生图主路径）"}],"paths":{"/api/v1/models":{"get":{"summary":"（可选）查模型列表","description":"可先看有哪些模型与积分，不挡生图。不会用就跳过，直接创建任务。\n\n### Header\n`Authorization: Bearer yj_live_...`\n\n### 四个模型（价格以本接口实时返回为准）\n- G2 `gpt-image-2.0` ≈ 100\n- G2-PRO `gpt-image-2-vip` ≈ 160\n- N2 `nano-banana-2` ≈ 140\n- N2-PRO `nano-banana-pro` ≈ 220","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/images/generations":{"post":{"summary":"① 创建图片任务","description":"主路径第一步：提交就能生图（与 GRSAI 一样：模型 + 提示词）。\n\n### Header\n`Authorization: Bearer yj_live_...`\n`Content-Type: application/json`\n\n### 字段\n- `model`：如 `gpt-image-2.0`\n- `prompt`：提示词\n- 可选：`aspect_ratio`（默认 `1:1`）、`image_size`（`1K`/`2K`/`4K`）、`n`（1–4）\n- 不要传 `size`（会 422）\n\n### Body 示例\n```json\n{\n  \"model\": \"gpt-image-2.0\",\n  \"prompt\": \"白底商品静物\",\n  \"aspect_ratio\": \"1:1\",\n  \"image_size\": \"1K\",\n  \"n\": 1\n}\n```\n\n返回后拿 `task_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"},"example":{"model":"gpt-image-2.0","prompt":"白底商品静物","aspect_ratio":"1:1","image_size":"1K","n":1}}}},"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":"task_demo_001","status":"queued","estimated_credits":100,"planned_model":"gpt-image-2.0"}}}},"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/{taskId}":{"get":{"summary":"② 查询图片结果 / 返图","description":"主路径第二步：用上一步的 `task_id` 轮询，任务结束后取图。\n\n### Header\n`Authorization: Bearer yj_live_...`\n\n### 只看两个字段\n- `task.terminal_status`：为 `false` 就按 `task.poll_after_seconds` 秒后继续查询；不要重新创建\n- 返图：任务结束且有 `task.images[0].url` 时取图\n\n### 成功示例\n```json\n{\n  \"ok\": true,\n  \"task\": {\n    \"id\": \"task_demo_001\",\n    \"status\": \"completed\",\n    \"terminal_status\": true,\n    \"images\": [\n      {\n        \"url\": \"https://yuanjing-ai.com/…/result.png\"\n      }\n    ]\n  }\n}\n```\n\n超时只查同一 `taskId`，不要重新 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"},"example":{"ok":true,"task":{"id":"task_demo_001","status":"completed","terminal_status":true,"images":[{"url":"https://yuanjing-ai.com/…/result.png"}]}}}}},"404":{"description":"Not found"}},"operationId":"getTask","tags":["源景图片生成"],"x-yuanjing-docs-pair":"POST /api/v1/images/generations"}},"/api/v1/agent/videos/quote":{"post":{"x-required-scope":"videos:write","security":[{"bearerAuth":[]}],"tags":["源景视频生成"],"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,"description":"**这一步只报价：不创建视频任务，不生成视频，也不能生图。**\n\n先报价、不扣费。拿到 `expected_credits` 与 `quote_fingerprint` 再进入「视频② 确认提交」。\n\n### Header\n`Authorization: Bearer yj_live_...`（需 `videos:write`）"}},"/api/v1/agent/videos/submit":{"post":{"x-required-scope":"videos:write","security":[{"bearerAuth":[]}],"tags":["源景视频生成"],"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,"description":"带上报价结果：`confirmed=true`、`expected_credits`、`quote_fingerprint`、`client_request_id`。\n相同请求映射同一会话；不要自动付费重跑。\n不含一键成片等站内工作流（见完整 OpenAPI）。"}},"/api/v1/agent/videos/tasks/{jobId}":{"get":{"x-required-scope":"videos:write","security":[{"bearerAuth":[]}],"tags":["源景视频生成"],"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,"description":"用提交返回的 `jobId` 查询。超时只查同一任务。"}}},"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":{"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}$"}}}]},"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"}}},"TaskResponse":{"type":"object","required":["ok","task"],"additionalProperties":false,"properties":{"ok":{"const":true},"task":{"$ref":"#/components/schemas/Task"}},"example":{"ok":true,"task":{"id":"task_demo_001","status":"completed","terminal_status":true,"images":[{"url":"https://yuanjing-ai.com/…/result.png"}]}}},"Task":{"type":"object","properties":{"id":{"type":"string","example":"task_demo_001"},"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"],"example":"completed"},"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"}}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}},"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"}}},"GenerationRequest":{"type":"object","required":["prompt"],"additionalProperties":false,"properties":{"prompt":{"type":"string","maxLength":4000,"description":"提示词，必填","example":"白底商品静物"},"model":{"type":"string","enum":["gpt-image-2.0","gpt-image-2-vip","nano-banana-2","nano-banana-pro"],"description":"选一个：G2=gpt-image-2.0(100) · G2-PRO=gpt-image-2-vip(160) · N2=nano-banana-2(140) · N2-PRO=nano-banana-pro(220)","example":"gpt-image-2.0"},"aspect_ratio":{"type":"string","default":"1:1","description":"比例，默认 1:1。当前文档支持：1:1 / 16:9 / 9:16 / 3:4 / 4:3 / 3:2 / 2:3 / 4:5 / 5:4。不要传 size；21:9 等极端比例本薄接口不承诺。","example":"1:1"},"image_size":{"type":"string","enum":["1K","2K","4K"],"description":"清晰度：1K / 2K / 4K（新手用 1K）","example":"1K"},"n":{"type":"integer","minimum":1,"maximum":4,"description":"张数 1–4，默认 1","example":1}},"example":{"model":"gpt-image-2.0","prompt":"白底商品静物","aspect_ratio":"1:1","image_size":"1K","n":1}},"ModelListResponse":{"type":"object","required":["object","data"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}},"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}}}}},"security":[{"bearerAuth":[]}],"x-yuanjing-docs-lite":{"models":["gpt-image-2.0","gpt-image-2-vip","nano-banana-2","nano-banana-pro"],"flow":["GET /api/v1/models","POST /api/v1/images/generations","GET /api/v1/tasks/{taskId}"],"video_flow":["POST /api/v1/agent/videos/quote","POST /api/v1/agent/videos/submit","GET /api/v1/agent/videos/tasks/{jobId}"],"excludes":["main-image","detail-page","poster","rewrite","custom-skills","one-click-video","agent-skill-install"],"full_openapi":"/openapi.json","foolproof":true}}