seedream_generate_image
Generate or edit images with Seedream (text-to-image, image-to-image, point/box edits).
Pass images to edit or use as references; point or bbox targets a spot on the first image. variations (up to 10) run in parallel; max_images is one provider batch on models that support it. background=‘transparent’ generates transparent PNGs from text or references on 5.5; 5.0 Pro requires an already-transparent PNG input. 5.5 supports auto background and standard optimization only. Layer decomposition and rich-text OCR are not supported; unknown input fields are rejected. Model limits: ark_list_models(kind=‘image’); requests outside them are rejected with every problem listed. dry_run=true returns request bodies and a cost estimate. Run through ark_job_submit.
| Requirement | Value |
|---|---|
| Registration | Requires BYTEPLUS_MODELARK_API_KEY. |
| Execution | Background required |
| Required permission | seedream:generate |
This site lists the full configured capability surface, not the tools enabled on your particular server. Use model discovery and job discovery to check your connection. Credentials are server configuration, never tool arguments.
Supported Models
Section titled “Supported Models”These are supported families and built-in model or service IDs for this site revision, not provider account access or a guarantee that every row is enabled on your server. Check model discovery for configured bindings and service availability.
| Model | Model or service ID | Availability | Capabilities |
|---|---|---|---|
| Seedream 5.5 | dola-seedream-5-5-261028 |
Built-in default; account authorization required. | 10 references; 1K, 1.5K, 2K (default); PNG (default) or JPEG; text-to-transparent PNG; auto, opaque, transparent backgrounds; standard optimization only; independent variations, no provider batch. |
| Seedream 5.0 Pro | dola-seedream-5-0-pro-260628 |
Opt-in default or configured binding (pro). |
10 references; PNG/JPEG; transparent edits require one already-transparent PNG; standard/fast optimization; independent variations, no provider batch. |
| Seedream Lite | Authorized custom ID; no built-in ID | Configure a lite family binding. |
14 references; PNG/JPEG; provider batch supported; no transparent background. |
| Seedream 4.x | Authorized custom ID; no built-in ID | Configure a 4x family binding. |
14 references; JPEG only; provider batch supported; no transparent background. |
Pass an exact configured ID as model, or omit it for SEEDREAM_DEFAULT_MODEL. Custom IDs require an explicit family binding in SEEDREAM_MODEL_BINDINGS. Explicit operator defaults remain unchanged.
Ask your connected AI client to use seedream_generate_image for the operation you want.
The client constructs the arguments and handles tool calls. Review its proposed
operation before approving anything billable. For a non-billable introduction,
start with discovery without generation.
Submit through ark_job_submit with tool_name and the complete target arguments, including its inner input object. Poll ark_job_get using the returned Ark job_id, respecting poll_after_ms. Inspect both terminal status and result.is_error; the original output is in result.structured_content. Do not call this tool in the foreground.
Exact MCP call (for developers)
The following is an MCP tool-call envelope, not a shell command. Example media URLs and identifiers must be replaced with your own accessible resources. Seedream and Seedance examples are non-billable dry runs; other provider operations may incur charges.
{ "name": "ark_job_submit", "arguments": { "input": { "tool_name": "seedream_generate_image", "arguments": { "input": { "model": "dola-seedream-5-5-261028", "prompt": "Embroidered heart and daisy patches, transparent background.", "size": "2K", "response_format": "url", "output_format": "png", "background": "transparent", "watermark": true, "dry_run": true } } } }}This reference describes the server revision built with this site. Older
installations, including v0.2.0, may not include 5.5. Follow
Update and Roll Back to select a reviewed revision.
Transparent Images and Editing
Section titled “Transparent Images and Editing”A transparent PNG can be generated with 5.5 from text alone or from references without existing alpha. Ask your connected agent:
Use Seedream 5.5 to create one 2K PNG of embroidered heart and daisypatches with raised stitching and off-white borders. Use a transparentbackground and enable the watermark. Show me the result and a downloadlink. If Seedream 5.5 is unavailable, stop and explain what is missing.Generation may incur charges. The exact MCP call above previews a transparent
PNG with dry_run=true, without generating or billing. Inspect
result.structured_content.preview; its cost is an estimate, not a bill.
Only change dry_run to false after approving a paid generation.
For editing, attach the source and describe the change. Reference counts are
model-specific, as shown above. Optional point or bbox coordinates target
the first image on a normalized 0-999 scale. Ordinary reference edits and
region prompts do not enable layer decomposition.
5.5 also accepts a positive custom WIDTHxHEIGHT: 921,600-4,624,220 pixels
inclusive, with width/height ratio 1/16-16. Every family supports 1-10 independent
variations; only batch-capable families accept max_images > 1, and batching
cannot be combined with multiple variations. On 5.5/Pro, optional
safety_identifier accepts 1-64 non-space printable ASCII characters; prefer a
stable hash, not personal data. It is redacted from previews and structured logs.
JPEG is always opaque, including with background="auto". Base64 delivery
requires persist=true. Pro transparency still requires exactly one
already-transparent PNG; it does not gain text-to-transparent generation.
Custom endpoint IDs must bind to family seedream_5_5. See the
model capabilities
and default upgrade note.
The adapter sends POST /api/v3/images/generations with Bearer authentication
and stream: false. persist, dry_run and the job envelope are MCP controls,
not provider payload fields. Keep keys in private server configuration.
Seedream 5.5 does not document the retained seed compatibility field in its
GA parameters or OpenAPI schema; omit it unless provider acceptance is verified.
Output Checks and Scope
Section titled “Output Checks and Scope”Delivery is not visual acceptance. Inspect item_errors, per-variation errors
and artifact persistence_error. Provider URLs expire; retain durable artifacts.
generations[].images[].inspection separately reports decoded dimensions,
format and has_transparency. Actual alpha below 255 differs from a PNG file
extension or a provider claim. Inspection is advisory and never triggers a
paid retry; URL-only delivery can leave inspection null.
Review text, composition and edit accuracy visually. See image inspection and the bounded review/edit workflow. After a timeout, recover the existing job instead of submitting again.
Layer decomposition and native rich-text OCR are not supported by this MCP
integration. layer_decomposition and layer_decomposition_options are
rejected even though the provider API documents the separate operation.
Inputs
Section titled “Inputs”The MCP arguments object wraps these fields as {"input": {...}}.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
background |
“auto”, “opaque”, “transparent” or null | No | 5.5 defaults to auto (prompt decides; jpeg is opaque). transparent requires png output; 5.5 accepts text or references without alpha, 5.0 Pro needs one already-transparent PNG. auto is 5.5-only.; Default: null |
bbox |
EditBbox or null | No | Edit: normalized (0-999) box on the first image. Requires images.; Default: null |
dry_run |
boolean | No | Validate and return the request bodies and a cost estimate; nothing is generated or billed.; Default: false |
images |
array of ReferenceImageInput or null | No | Reference or source images (per-model max in ark_list_models(kind=‘image’)).; Default: null |
max_images |
integer or null | No | Images from one provider call (1-15), on models that support batches. Not combinable with variations > 1.; Default: null |
model |
string or null | No | Exact model ID from ark_list_models(kind=‘image’); the default if omitted.; Default: null |
output_format |
“png”, “jpeg” or null | No | Output format. Defaults to png on 5.5 and for transparent backgrounds; otherwise provider default.; Default: null |
output_path |
string or null | No | Optional local destination for the generated images: a file, or a directory when it ends with ’/’ (files named <artifact_id>. |
overwrite |
boolean | No | Replace an existing file at output_path/output_dir when its content differs (identical content is always accepted).; Default: false |
persist |
boolean | No | Persist images as durable MCP resources.; Default: true |
point |
EditCoordinate or null | No | Edit: normalized (0-999) point on the first image. Requires images.; Default: null |
prompt |
string or null | No | Prompt or edit instruction (1-4,000 characters including point/bbox markup). Required unless variation_prompts is set.; Default: null |
prompt_optimization |
“standard”, “fast” or null | No | 5.5: standard only (provider default); fast is rejected. 5.0 Pro: standard or fast, default SEEDREAM_PROMPT_OPTIMIZATION_MODE.; Default: null |
response_format |
“url”, “b64_json” or null | No | Provider response format: URL or Base64 JSON (requires persist=true).; Default: null |
safety_identifier |
string or null | No | 5.5/5.0 Pro: stable end-user ID, 1-64 non-space printable ASCII characters. Use a hash, not personal data.; Default: null |
seed |
integer or null | No | Seed compatibility field; 5.5 support is undocumented, so omit unless verified. With variations > 1: N gives variation i seed N + i; -1 picks a random seed per variation; omitted lets the provider randomize.; Default: null |
size |
string or null | No | 5.5: 1K, 1.5K, 2K (default), or WIDTHxHEIGHT: 921600-4624220 pixels, ratio 1:16-16:1.; Default: null |
variation_prompts |
array of string or null | No | One prompt per variation, overriding prompt; exactly variations entries.; Default: null |
variations |
integer | No | Parallel generations (1-10); failures are reported per variation.; minimum: 1; maximum: 10; Default: 1 |
watermark |
boolean or null | No | Apply an AIGC watermark.; Default: null |
Outputs
Section titled “Outputs”| Field | Type | Required | Description and constraints |
|---|---|---|---|
artifacts |
array of ArtifactRef | No | Images from a single call (variations=1). Empty for variations and dry runs. |
created_at |
string | Yes | ISO-8601 timestamp of generation. |
dry_run |
boolean | No | True when nothing was generated; see preview.; Default: false |
generations |
array of SeedreamGenerationMetadata | No | Completed-call provenance, provider reports and byte checks; empty for dry runs. |
item_errors |
array of SeedreamItemError | No | Single-call image errors, including NO_OUTPUT and NO_DELIVERABLE_OUTPUT. |
model |
string | Yes | Model ID used for generation. |
preview |
SeedreamGeneratePreview or null | No | Request bodies and cost estimate; set only for a dry run.; Default: null |
provider |
“byteplus-modelark” | No | Provider that generated the images.; Default: “byteplus-modelark” |
summary |
VariationSummary or null | No | Per-variation results (seed, artifact or error) when variations > 1.; Default: null |
usage |
SeedreamUsage or null | No | Provider image/token usage; null for variations and dry runs.; Default: null |
Nested Types
Section titled “Nested Types”Field types named above refer to these shared definitions. Optional/null fields, enum choices and bounds are retained in the complete schemas below. Schema validation is followed by runtime capability and security checks.
EditBbox
| Field | Type | Required | Description and constraints |
|---|---|---|---|
x1 |
integer | Yes | Left edge.; minimum: 0; maximum: 999 |
x2 |
integer | Yes | Right edge.; minimum: 0; maximum: 999 |
y1 |
integer | Yes | Top edge.; minimum: 0; maximum: 999 |
y2 |
integer | Yes | Bottom edge.; minimum: 0; maximum: 999 |
EditCoordinate
| Field | Type | Required | Description and constraints |
|---|---|---|---|
x |
integer | Yes | Horizontal position, 0=left, 999=right.; minimum: 0; maximum: 999 |
y |
integer | Yes | Vertical position, 0=top, 999=bottom.; minimum: 0; maximum: 999 |
MediaSourceKind
No fields. Pass {}.
ReferenceImageInput
| Field | Type | Required | Description and constraints |
|---|---|---|---|
data |
string or null | No | Base64-encoded media data. Required when kind is ‘base64’.; Default: null |
kind |
MediaSourceKind | Yes | Whether the media is referenced by URL or Base64. |
mime_type |
string or null | No | MIME type of the media (e.g. image/png, audio/wav).; Default: null |
url |
string or null | No | HTTPS URL of the media, or ‘asset://<asset_id>’ for an Active private asset library asset (ark_asset_create). Required when kind is ‘url’.; Default: null |
SeedreamGenerateInput
| Field | Type | Required | Description and constraints |
|---|---|---|---|
background |
“auto”, “opaque”, “transparent” or null | No | 5.5 defaults to auto (prompt decides; jpeg is opaque). transparent requires png output; 5.5 accepts text or references without alpha, 5.0 Pro needs one already-transparent PNG. auto is 5.5-only.; Default: null |
bbox |
EditBbox or null | No | Edit: normalized (0-999) box on the first image. Requires images.; Default: null |
dry_run |
boolean | No | Validate and return the request bodies and a cost estimate; nothing is generated or billed.; Default: false |
images |
array of ReferenceImageInput or null | No | Reference or source images (per-model max in ark_list_models(kind=‘image’)).; Default: null |
max_images |
integer or null | No | Images from one provider call (1-15), on models that support batches. Not combinable with variations > 1.; Default: null |
model |
string or null | No | Exact model ID from ark_list_models(kind=‘image’); the default if omitted.; Default: null |
output_format |
“png”, “jpeg” or null | No | Output format. Defaults to png on 5.5 and for transparent backgrounds; otherwise provider default.; Default: null |
output_path |
string or null | No | Optional local destination for the generated images: a file, or a directory when it ends with ’/’ (files named <artifact_id>. |
overwrite |
boolean | No | Replace an existing file at output_path/output_dir when its content differs (identical content is always accepted).; Default: false |
persist |
boolean | No | Persist images as durable MCP resources.; Default: true |
point |
EditCoordinate or null | No | Edit: normalized (0-999) point on the first image. Requires images.; Default: null |
prompt |
string or null | No | Prompt or edit instruction (1-4,000 characters including point/bbox markup). Required unless variation_prompts is set.; Default: null |
prompt_optimization |
“standard”, “fast” or null | No | 5.5: standard only (provider default); fast is rejected. 5.0 Pro: standard or fast, default SEEDREAM_PROMPT_OPTIMIZATION_MODE.; Default: null |
response_format |
“url”, “b64_json” or null | No | Provider response format: URL or Base64 JSON (requires persist=true).; Default: null |
safety_identifier |
string or null | No | 5.5/5.0 Pro: stable end-user ID, 1-64 non-space printable ASCII characters. Use a hash, not personal data.; Default: null |
seed |
integer or null | No | Seed compatibility field; 5.5 support is undocumented, so omit unless verified. With variations > 1: N gives variation i seed N + i; -1 picks a random seed per variation; omitted lets the provider randomize.; Default: null |
size |
string or null | No | 5.5: 1K, 1.5K, 2K (default), or WIDTHxHEIGHT: 921600-4624220 pixels, ratio 1:16-16:1.; Default: null |
variation_prompts |
array of string or null | No | One prompt per variation, overriding prompt; exactly variations entries.; Default: null |
variations |
integer | No | Parallel generations (1-10); failures are reported per variation.; minimum: 1; maximum: 10; Default: 1 |
watermark |
boolean or null | No | Apply an AIGC watermark.; Default: null |
Complete JSON Schemas
Section titled “Complete JSON Schemas”Input schema, including the MCP wrapper
{ "$defs": { "EditBbox": { "description": "Normalized bounding box (0-999) for region-based editing.", "properties": { "x1": { "description": "Left edge.", "maximum": 999, "minimum": 0, "type": "integer" }, "x2": { "description": "Right edge.", "maximum": 999, "minimum": 0, "type": "integer" }, "y1": { "description": "Top edge.", "maximum": 999, "minimum": 0, "type": "integer" }, "y2": { "description": "Bottom edge.", "maximum": 999, "minimum": 0, "type": "integer" } }, "required": [ "x1", "y1", "x2", "y2" ], "type": "object" }, "EditCoordinate": { "description": "Normalized point coordinate (0-999) for interactive editing.", "properties": { "x": { "description": "Horizontal position, 0=left, 999=right.", "maximum": 999, "minimum": 0, "type": "integer" }, "y": { "description": "Vertical position, 0=top, 999=bottom.", "maximum": 999, "minimum": 0, "type": "integer" } }, "required": [ "x", "y" ], "type": "object" }, "MediaSourceKind": { "description": "Whether a media source is a URL or inline Base64 data.", "enum": [ "url", "base64" ], "type": "string" }, "ReferenceImageInput": { "description": "A reference image by URL, Base64 data, or private asset (``asset://<asset_id>``).", "properties": { "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Base64-encoded media data. Required when kind is 'base64'." }, "kind": { "$ref": "#/$defs/MediaSourceKind", "description": "Whether the media is referenced by URL or Base64." }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "MIME type of the media (e.g. image/png, audio/wav)." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HTTPS URL of the media, or 'asset://<asset_id>' for an Active private asset library asset (ark_asset_create). Required when kind is 'url'." } }, "required": [ "kind" ], "type": "object" }, "SeedreamGenerateInput": { "additionalProperties": false, "description": "Input model for ``seedream_generate_image``.", "properties": { "background": { "anyOf": [ { "enum": [ "auto", "opaque", "transparent" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "5.5 defaults to auto (prompt decides; jpeg is opaque). transparent requires png output; 5.5 accepts text or references without alpha, 5.0 Pro needs one already-transparent PNG. auto is 5.5-only." }, "bbox": { "anyOf": [ { "$ref": "#/$defs/EditBbox" }, { "type": "null" } ], "default": null, "description": "Edit: normalized (0-999) box on the first image. Requires images." }, "dry_run": { "default": false, "description": "Validate and return the request bodies and a cost estimate; nothing is generated or billed.", "type": "boolean" }, "images": { "anyOf": [ { "items": { "$ref": "#/$defs/ReferenceImageInput" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Reference or source images (per-model max in ark_list_models(kind='image'))." }, "max_images": { "anyOf": [ { "maximum": 15, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Images from one provider call (1-15), on models that support batches. Not combinable with variations > 1." }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Exact model ID from ark_list_models(kind='image'); the default if omitted." }, "output_format": { "anyOf": [ { "enum": [ "png", "jpeg" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Output format. Defaults to png on 5.5 and for transparent backgrounds; otherwise provider default." }, "output_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional local destination for the generated images: a file, or a directory when it ends with '/' (files named <artifact_id>.<ext>). A directory is required when several images are produced. stdio only; absolute path inside an allowed output root (client MCP roots or OUTPUT_ROOTS). The durable artifact is always kept; the copy is reported in ArtifactRef.local_path." }, "overwrite": { "default": false, "description": "Replace an existing file at output_path/output_dir when its content differs (identical content is always accepted).", "type": "boolean" }, "persist": { "default": true, "description": "Persist images as durable MCP resources.", "type": "boolean" }, "point": { "anyOf": [ { "$ref": "#/$defs/EditCoordinate" }, { "type": "null" } ], "default": null, "description": "Edit: normalized (0-999) point on the first image. Requires images." }, "prompt": { "anyOf": [ { "maxLength": 4000, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Prompt or edit instruction (1-4,000 characters including point/bbox markup). Required unless variation_prompts is set." }, "prompt_optimization": { "anyOf": [ { "enum": [ "standard", "fast" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "5.5: standard only (provider default); fast is rejected. 5.0 Pro: standard or fast, default SEEDREAM_PROMPT_OPTIMIZATION_MODE." }, "response_format": { "anyOf": [ { "enum": [ "url", "b64_json" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider response format: URL or Base64 JSON (requires persist=true)." }, "safety_identifier": { "anyOf": [ { "maxLength": 64, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" }, { "type": "null" } ], "default": null, "description": "5.5/5.0 Pro: stable end-user ID, 1-64 non-space printable ASCII characters. Use a hash, not personal data." }, "seed": { "anyOf": [ { "maximum": 2147483647, "minimum": -1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Seed compatibility field; 5.5 support is undocumented, so omit unless verified. With variations > 1: N gives variation i seed N + i; -1 picks a random seed per variation; omitted lets the provider randomize." }, "size": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "5.5: 1K, 1.5K, 2K (default), or WIDTHxHEIGHT: 921600-4624220 pixels, ratio 1:16-16:1." }, "variation_prompts": { "anyOf": [ { "items": { "maxLength": 4000, "minLength": 1, "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "One prompt per variation, overriding prompt; exactly `variations` entries." }, "variations": { "default": 1, "description": "Parallel generations (1-10); failures are reported per variation.", "maximum": 10, "minimum": 1, "type": "integer" }, "watermark": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Apply an AIGC watermark." } }, "type": "object" } }, "additionalProperties": false, "properties": { "input": { "$ref": "#/$defs/SeedreamGenerateInput" } }, "required": [ "input" ], "type": "object"}Output schema, including nested definitions
{ "$defs": { "ArtifactPersistenceIssue": { "description": "Safe explanation for a provider output that could not be persisted.", "properties": { "artifact_limit_bytes": { "description": "Maximum durable artifact size in bytes.", "title": "Artifact Limit Bytes", "type": "integer" }, "code": { "description": "Failure category.", "enum": [ "untrusted_output_host", "output_too_large", "invalid_output_mime", "source_expired", "download_failed", "storage_failed" ], "title": "Code", "type": "string" }, "message": { "description": "Safe failure message (no credentials or URLs).", "title": "Message", "type": "string" }, "retryable": { "description": "Whether retrying persistence later may succeed.", "title": "Retryable", "type": "boolean" }, "source_url_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of the unpersisted provider URL (the artifact uri).", "title": "Source Url Expires At" } }, "required": [ "code", "message", "retryable", "artifact_limit_bytes" ], "title": "ArtifactPersistenceIssue", "type": "object" }, "ArtifactRef": { "description": "Stable reference to a persisted media artifact.", "properties": { "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Size in bytes.", "title": "Bytes" }, "created_at": { "description": "ISO-8601 timestamp of artifact creation.", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of the stored artifact.", "title": "Expires At" }, "export_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the requested local copy was not written (the artifact is unaffected).", "title": "Export Error" }, "fallback_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Base64 output bytes, only with id 'inline-fallback'.", "title": "Fallback Data" }, "id": { "description": "Unique artifact identifier.", "title": "Id", "type": "string" }, "local_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Absolute path of the local copy written for output_path/output_dir.", "title": "Local Path" }, "media_type": { "$ref": "#/$defs/MediaType", "description": "image, audio, video or three_d." }, "mime_type": { "description": "MIME type, e.g. image/png.", "title": "Mime Type", "type": "string" }, "persistence_error": { "anyOf": [ { "$ref": "#/$defs/ArtifactPersistenceIssue" }, { "type": "null" } ], "default": null, "description": "Set when the output was billed but not stored. id is then 'provider-url' (uri is the temporary provider URL; re-persist it with seed_media_persist_url before source_expires_at) or 'inline-fallback' (bytes in fallback_data)." }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 hex digest.", "title": "Sha256" }, "source_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of the provider URL.", "title": "Source Expires At" }, "uri": { "description": "MCP resource URI (seed-media://artifacts/{id}).", "title": "Uri", "type": "string" } }, "required": [ "id", "uri", "media_type", "mime_type", "created_at" ], "title": "ArtifactRef", "type": "object" }, "JsonValue": {}, "MediaType": { "description": "Logical generated-media categories.", "enum": [ "image", "audio", "video", "three_d" ], "title": "MediaType", "type": "string" }, "SeedreamGeneratePreview": { "description": "What a dry run would have submitted.", "properties": { "estimated_cost_usd": { "description": "Estimated USD using cached account pricing or built-in fallback; not billing.", "title": "Estimated Cost Usd", "type": "number" }, "price_source": { "default": "builtin", "description": "catalog: cached account image rate; builtin: fallback estimate.", "enum": [ "catalog", "builtin" ], "title": "Price Source", "type": "string" }, "requests": { "description": "Provider request bodies that would be sent, one per variation. Reference image URLs are reduced to scheme and host, inline Base64 to its size, and safety_identifier redacted.", "items": { "additionalProperties": { "$ref": "#/$defs/JsonValue" }, "type": "object" }, "title": "Requests", "type": "array" } }, "required": [ "requests", "estimated_cost_usd" ], "title": "SeedreamGeneratePreview", "type": "object" }, "SeedreamGenerationMetadata": { "description": "Metadata for one completed Seedream provider call.", "properties": { "images": { "description": "Image metadata in provider data order.", "items": { "$ref": "#/$defs/SeedreamImageMetadata" }, "title": "Images", "type": "array" }, "prompt_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 of the UTF-8 submitted prompt including edit markup.", "title": "Prompt Sha256" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider request ID; null if absent.", "title": "Request Id" }, "request_options": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "boolean" } ] }, "description": "Allowlisted submitted options and reference count; excludes prompt, media and identifiers. Omitted options use provider defaults.", "title": "Request Options", "type": "object" }, "safety_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider-echoed end-user identifier; null if absent.", "title": "Safety Identifier" }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Submitted seed; -1 or null means provider randomness, not a recovered seed.", "title": "Seed" }, "usage": { "anyOf": [ { "$ref": "#/$defs/SeedreamUsage" }, { "type": "null" } ], "default": null, "description": "Per-call usage; null if absent." }, "variation_index": { "description": "Zero-based variation index; 0 for single calls.", "title": "Variation Index", "type": "integer" } }, "required": [ "variation_index" ], "title": "SeedreamGenerationMetadata", "type": "object" }, "SeedreamImageInspection": { "description": "Local byte inspection, independent of provider reports and visual quality.", "properties": { "has_transparency": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when decoded pixels contain alpha below 255; null if unchecked.", "title": "Has Transparency" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Decoded height in pixels.", "title": "Height" }, "issues": { "description": "Safe byte-check or claim-mismatch codes; no paid retries.", "items": { "type": "string" }, "title": "Issues", "type": "array" }, "output_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Byte-detected png or jpeg format.", "title": "Output Format" }, "status": { "description": "Byte checks passed, claims differ, bytes invalid, or inspection unavailable.", "enum": [ "verified", "mismatch", "invalid", "unavailable" ], "title": "Status", "type": "string" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Decoded width in pixels.", "title": "Width" } }, "required": [ "status" ], "title": "SeedreamImageInspection", "type": "object" }, "SeedreamImageMetadata": { "description": "Provider-reported image properties, not inferred from the request.", "properties": { "artifact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Matching artifact ID, or null without output.", "title": "Artifact Id" }, "background": { "anyOf": [ { "enum": [ "opaque", "transparent" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Actual provider-reported background; null if absent.", "title": "Background" }, "index": { "description": "Zero-based position in provider data.", "title": "Index", "type": "integer" }, "inspection": { "anyOf": [ { "$ref": "#/$defs/SeedreamImageInspection" }, { "type": "null" } ], "default": null, "description": "Local byte checks; null for URL-only delivery or no artifact." }, "output_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Returned image format; null if absent.", "title": "Output Format" }, "size": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Returned WIDTHxHEIGHT in pixels; null if absent.", "title": "Size" } }, "required": [ "index" ], "title": "SeedreamImageMetadata", "type": "object" }, "SeedreamItemError": { "description": "Error for a single failed image in a batch generation.", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider error code.", "title": "Code" }, "index": { "description": "0-based index of the failed image.", "title": "Index", "type": "integer" }, "message": { "description": "Error description.", "title": "Message", "type": "string" } }, "required": [ "index", "message" ], "title": "SeedreamItemError", "type": "object" }, "SeedreamUsage": { "description": "Usage information for a Seedream image generation call.", "properties": { "completion_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Completion tokens consumed.", "title": "Completion Tokens" }, "generated_images": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Generated image count.", "title": "Generated Images" }, "input_images": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Input image count reported by provider.", "title": "Input Images" }, "output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Output tokens reported by provider.", "title": "Output Tokens" }, "prompt_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Prompt tokens consumed.", "title": "Prompt Tokens" }, "total_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total tokens consumed.", "title": "Total Tokens" } }, "title": "SeedreamUsage", "type": "object" }, "VariationError": { "description": "Machine-readable failure for one variation.", "properties": { "ambiguous_completion": { "default": false, "description": "Whether the provider may have partially completed despite the error.", "title": "Ambiguous Completion", "type": "boolean" }, "code": { "description": "Error code (e.g. PROVIDER_ERROR, TIMEOUT, UNEXPECTED_ERROR).", "title": "Code", "type": "string" }, "message": { "default": "", "description": "Human-readable error message.", "title": "Message", "type": "string" }, "phase": { "anyOf": [ { "enum": [ "queued", "generating", "persisting" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Stage at failure: 'queued' (never started, safe to retry), 'generating' (may have completed), or 'persisting' (generated, storing failed).", "title": "Phase" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider request ID, if available.", "title": "Request Id" }, "retryable": { "default": false, "description": "Whether the caller may retry this variation.", "title": "Retryable", "type": "boolean" } }, "required": [ "code" ], "title": "VariationError", "type": "object" }, "VariationResult": { "description": "Result of a single variation within a parallel generation.", "properties": { "artifact": { "anyOf": [ { "$ref": "#/$defs/ArtifactRef" }, { "type": "null" } ], "default": null, "description": "Generated artifact (None if failed)." }, "error": { "anyOf": [ { "$ref": "#/$defs/VariationError" }, { "type": "null" } ], "default": null, "description": "Error if this variation failed." }, "index": { "description": "0-based variation index.", "title": "Index", "type": "integer" }, "provider_log_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider-side log ID for troubleshooting.", "title": "Provider Log Id" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Request ID for this variation.", "title": "Request Id" }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Seed used (if applicable).", "title": "Seed" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider task ID, when the variation created a task.", "title": "Task Id" } }, "required": [ "index" ], "title": "VariationResult", "type": "object" }, "VariationSummary": { "description": "Aggregate result of a parallel generation.", "properties": { "failed": { "description": "Variations that failed.", "title": "Failed", "type": "integer" }, "succeeded": { "description": "Variations that produced output.", "title": "Succeeded", "type": "integer" }, "total": { "description": "Total variations requested.", "title": "Total", "type": "integer" }, "variations": { "description": "Per-variation results (artifacts, errors, and metadata).", "items": { "$ref": "#/$defs/VariationResult" }, "title": "Variations", "type": "array" } }, "required": [ "total", "succeeded", "failed" ], "title": "VariationSummary", "type": "object" } }, "description": "Output model for ``seedream_generate_image``.", "properties": { "artifacts": { "description": "Images from a single call (variations=1). Empty for variations and dry runs.", "items": { "$ref": "#/$defs/ArtifactRef" }, "title": "Artifacts", "type": "array" }, "created_at": { "description": "ISO-8601 timestamp of generation.", "title": "Created At", "type": "string" }, "dry_run": { "default": false, "description": "True when nothing was generated; see preview.", "title": "Dry Run", "type": "boolean" }, "generations": { "description": "Completed-call provenance, provider reports and byte checks; empty for dry runs.", "items": { "$ref": "#/$defs/SeedreamGenerationMetadata" }, "title": "Generations", "type": "array" }, "item_errors": { "description": "Single-call image errors, including NO_OUTPUT and NO_DELIVERABLE_OUTPUT.", "items": { "$ref": "#/$defs/SeedreamItemError" }, "title": "Item Errors", "type": "array" }, "model": { "description": "Model ID used for generation.", "title": "Model", "type": "string" }, "preview": { "anyOf": [ { "$ref": "#/$defs/SeedreamGeneratePreview" }, { "type": "null" } ], "default": null, "description": "Request bodies and cost estimate; set only for a dry run." }, "provider": { "const": "byteplus-modelark", "default": "byteplus-modelark", "description": "Provider that generated the images.", "title": "Provider", "type": "string" }, "summary": { "anyOf": [ { "$ref": "#/$defs/VariationSummary" }, { "type": "null" } ], "default": null, "description": "Per-variation results (seed, artifact or error) when variations > 1." }, "usage": { "anyOf": [ { "$ref": "#/$defs/SeedreamUsage" }, { "type": "null" } ], "default": null, "description": "Provider image/token usage; null for variations and dry runs." } }, "required": [ "model", "created_at" ], "title": "SeedreamGenerateOutput", "type": "object"}Troubleshooting
Section titled “Troubleshooting”- Missing tool: check provider credentials and feature flags, then restart the connection.
- Invalid arguments: keep the correct wrapper and follow current model limits from discovery. A valid schema alone does not prove the chosen model supports the combination.
- A job completes with an error: inspect the original tool result, not only the outer job status. Never automatically resubmit potentially billable work.
- Local output writes from jobs require server-configured
OUTPUT_ROOTS; HTTP cannot write to a client’s local disk.
See configuration, background execution, and artifact delivery.