Skip to content

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.

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.

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 daisy
patches with raised stitching and off-white borders. Use a transparent
background and enable the watermark. Show me the result and a download
link. 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.

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.

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>.). 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.; Default: null
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
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

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>.). 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.; Default: null
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
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"
}
  • 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.